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Introduction 


T his book — the 6 th edition of Programming Windows — is a guide to writing 
applications that run under Microsoft Windows 8. 

To use this book, you’ll need a computer running Windows 8, on which you can 
install the Windows 8 development tools and software development kit (SDK), most 
conveniently in the form of the free download of Microsoft Visual Studio Express 2012 
for Windows 8. That download is accessible from the Windows 8 developer portal: 

http://msdn.microsoft. com/windows/apps 

To install Visual Studio, follow the "Downloads for developers" link on that page and 
then the "Download the tools and SDK” link on the following page. This page also 
provides information on obtaining a Windows 8 developer account that lets you upload 
new applications to the Windows Store. 


The Versions of Windows 8 


For the most part, Windows 8 is intended to run on the same class of personal 
computers as Windows 7, which are machines built around the 32-bit or 64-bit Intel 
x86 microprocessor family. Windows 8 is available in a regular edition called simply 
Windows 8 and also a Windows 8 Pro edition with additional features that appeal to 
tech enthusiasts and professionals. 

Both Windows 8 and Windows 8 Pro run two types of programs: 

■ Desktop applications 

■ New Windows 8 applications, often called Windows Store applications 

Desktop applications are traditional Windows programs that currently run under 
Windows 7 and that interact with the operating system through the Windows 
application programming interface, known familiarly as the Win32 API. To run these 
desktop applications, Windows 8 includes a familiar Windows desktop screen. 



The new Windows Store applications represent a radical break with traditional 
Windows. The programs generally run in a full-screen mode — although two programs 
can share the screen in a "snap” mode — and many of these programs will probably be 
optimized for touch and tablet use. These applications are purchasable and installable 
only from the application store run by Microsoft. (As a developer, you can deploy and 
test applications directly from Visual Studio.) 

In addition to the versions of Windows 8 that run on x86 processors, there is also a 
version of Windows 8 that runs on ARM processors, most commonly found in low-cost 
tablets and other mobile devices. This version of Windows 8 is called Windows RT, 
and it only comes preinstalled on these machines. One of the first computers running 
Windows RT is the initial release of the Microsoft Surface. 

Aside from some preinstalled desktop applications, Windows RT runs new Windows 
Store applications only. You cannot run existing Windows 7 applications under 
Windows RT. You cannot run Visual Studio under Windows RT, and you cannot develop 
Windows 8 applications under Windows RT. 


The Windows 8 user interface incorporates a new design paradigm that is likely to 
be reflected in Windows Store applications. Somewhat inspired by signage in urban 
environments, this design paradigm emphasizes content over program "chrome" and is 
characterized by the use of unadorned fonts, clean open styling, a tile-based interface, 
and transitional animations. 

Many developers were first introduced to the Windows 8 design paradigm with 
Windows Phone 7, so it’s interesting to see how Microsoft’s thinking concerning large 
and small computers has evolved. In years gone by, Microsoft attempted to adapt the 
design of the traditional Windows desktop to smaller devices such as hand-held com¬ 
puters and phones. Now a user-interface design for the phone is being moved up to 
tablets and the desktop. 

One important characteristic of this new environment is an emphasis on multitouch, 
which has dramatically changed the relationship between human and computer. In 
fact, the term "multitouch" is now outmoded because virtually all new touch devices 
respond to multiple fingers. The simple word "touch” is now sufficient. Part of the 
new programming interface for Windows 8 applications treats touch, mouse, and 
pen input in a unified manner so that applications are automatically usable with all 
three input devices. 
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The Focus of This Book 


This book focuses exclusively on writing Windows Store applications. Plenty of other 
books already exist for writing Win32 desktop applications, including the 5 th edition 
of Programming Windows. Ill occasionally make reference to Win32 API and desktop 
applications, but this book is really all about writing new Windows 8 applications. 

For writing these applications, a new object-oriented API has been introduced called 
the Windows Runtime or WinRT (not to be confused with the version of Windows 8 that 
runs on ARM processors, called Windows RT). Internally, the Windows Runtime is based 
on COM (Component Object Model) with interfaces exposed through metadata files 
with the extension .winmd located in the /Win dows/System32/Win Me to do to directory. 
Externally, it is very object-oriented. 

From the application programmer’s perspective, the Windows Runtime resembles 
Silverlight, although internally it is not a managed API. For Silverlight programmers, 
perhaps the most immediate difference involves namespace names: the Silverlight 
namespaces beginning with System.Windows have been replaced with namespaces 
beginning with Windows.Ul.Xoml. 

Most Windows 8 applications will be built not only from code but also markup, 
either the industry-standard HyperText Markup Language (HTML) or Microsoft’s 
extensible Application Markup Language (XAML). One advantage of splitting an 
application between code and markup is potentially splitting the development of the 
application between programmers and designers. 

Currently there are three main options for writing Windows 8 applications, each of 
which involves a programming language and a markup language: 

■ C++ with XAML 

■ C# or Visual Basic with XAML 

■ JavaScript with HTML5 


The Windows Runtime is common to all these options, but the Windows Runtime is 
also supplemented by another programming interface appropriate for the particular 
language. Although you can’t mix languages within a single application, you can create 
libraries (called Windows Runtime Components) with their own .winmd files that can be 
accessed from any other Windows 8 language. 
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The C++ programmer uses a dialect of C++ called C++ with Component 
Extensions, or C++/CX, that allows the language to make better use of WinRT. The C++ 
programmer also has direct access to a subset of the Win32 and COM APIs, as well as 
DirectX. C++ programs are compiled to native machine code. 

Programmers who use the managed languages C# or Visual Basic .NET will find 
WinRT to be very familiar territory. Windows 8 applications written in these languages 
can’t access Win32, COM, or DirectX APIs with as much ease as the C++ programmer, 
but it is possible to do so, and some sample programs in Chapter 15, "Going Native," 
show how. A stripped-down version of .NET is also available for performing low-level 
tasks. 

For JavaScript the Windows Runtime is supplemented by a Windows Library for 
JavaScript, or WinJS, which provides a number of system-level features for Windows 8 
apps. 

After much consideration (and some anguish), I decided that this book would focus 
almost exclusively on the C# and XAML option. For at least a decade I have been con¬ 
vinced of the advantages of managed languages for development and debugging, and 
for me C# is the language that has the closest fit to the Windows Runtime. I hope C++ 
programmers find C# code easy enough to read to derive some benefit from this book. 

I also believe that a book focusing on one language option is more valuable than 
one that tries for equal coverage among several languages. There will undoubtedly be 
plenty of other Windows 8 books that show how to write Windows 8 applications using 
the other options. 

With that said, I have greatly enjoyed the renewed debate about the advantages of 
C++ and native code in crafting high-performance applications. No single tool is best 
for every problem, and I will be exploring C++ and DirectX development for Windows 8 
more in the future, both in my blog and the pages of MSDN Magazine. As a modest 
start, the companion content for this book includes all the program samples converted 
to C++. 
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The Approach 


In writing this book, I’ve made a couple assumptions about you, the reader. I assume 
that you are comfortable with C#. If not, you might want to supplement this book with 
a C# tutorial. If you are coming to C# from a C or C++ background, my free online book 
•NET Book Zero: What the C or C++ Programmer Needs to Know About C# and the .NET 
Framework might be adequate. This book is available in PDF or XPS format at 
www.charlespe tzold.co m/dotnet. 

I also assume that you know the rudimentary syntax of XML (extensible Markup 
Language) because XAML is based on XML. But I assume no familiarity with XAML or 
any XAML-based programming interface. 

This is an API book rather than a tools book. The only programming tool I use in this 
book is Microsoft Visual Studio Express 2012 for Windows 8 (which I’ll generally simply 
refer to as Visual Studio). 

Markup languages are generally much more toolable than programming code. 
Indeed, some programmers even believe that markup such as XAML should be entirely 
machine-generated. Visual Studio has a built-in interactive XAML designer that 
involves dragging controls to a page, and many programmers have come to know and 
love Microsoft Expression Blend for generating complex XAML for their applications. 
(Expression Blend is included among the free download of the development tools and 
SDK I mentioned earlier.) 

While such design tools are great for experienced programmers, I think that the 
programmer new to the environment is better served by learning how to write XAML 
by hand. That's how 111 approach XAML in this book. The XAML Cruncher tool featured 
in Chapter 8, "App Bars and Popups," is very much in keeping with this philosophy: it 
lets you type in XAML and interactively see the objects that are generated, but it does 
not try to write XAML for you. 

On the other hand, some programmers become so skilled at working with XAML 
that they forget how to create and initialize certain objects in code! I think both skills 
are important, and consequently I often show how to do similar tasks in both code 
and markup. 
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As I began working on this book, I contemplated different approaches to how a 
tutorial about the Windows Runtime can be structured. One approach is to start with 
rather low-level graphics and user input, demonstrate how controls can be built, and 
then describe the controls that have already been built for you. 

I have instead chosen to focus initially on those skills I think are most important for 
most mainstream programmers: assembling the predefined controls in an application 
and linking them with code and data. This is the focus of the 12 chapters of the book’s 
Part I, "Elementals.” One of my goals in Part I is to make comprehensible all the code 
and markup that Visual Studio generates in the various project templates it supports. 

Part II, "Specialities,” covers more low-level and esoteric tasks, such as touch, bitmap 
graphics, rich text, printing, and working with the orientation and GPS sensors. 


Source Code 


Learning a new API is similar to learning how to play basketball or the oboe: You don’t 
get the full benefit by watching someone else do it. Your own fingers must get involved. 
The source code in these pages is downloadable via the "Companion Content” link here: 

http://shop.oreilly.com/product/0790145369079.do 


But you’ll learn better by actually typing in the code yourself. 


My Setup 

For writing this book, I used the special version of the Samsung 700T tablet that was 
distributed to attendees of the Microsoft Build Conference in September 2011. (For 
that reason, it’s sometimes called the Build Tablet.) This machine has an Intel Core i5 
processor running at 1.6 GHz with 4 GB of RAM and a 64-GB hard drive. The screen 
(from which most of the screenshots in the book were taken) has 8 touch points and a 
resolution of 1366 x 768 pixels, which is the lowest resolution for which snap views are 
supported. 

Although the Build Tablets were originally distributed with the Windows 8 Developer 
Preview installed, I progressively replaced that with the Consumer Preview (build 8250) 
in March 2012 and the Release Preview (build 8400) in June 2012, and eventually the 
official release of Windows 8 Pro. Except when testing orientation sensors, I generally 
used the tablet in the docking port with an external 1920x1080 HDMI monitor, and an 
external keyboard and mouse. 
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When the Microsoft Surface first became available, I purchased one for testing my 
applications. For deploying and debugging applications on the Surface, I used the 
technique discussed by Tim Heuer in his blog entry: 

http://timheuer.com/blog/archive/2012/10/26/remote-debugging-windows-store- 
apps-on-surface-arm-devices, aspx 

This technique is more formally described in the documentation topic "Running 
Windows Store apps on a remote machine": 

h ttp://msdn. microsoft. com/e n- us/libra ry/h h441469. aspx 

The Surface became particularly vital for testing programs that access the orientation 
sensors. 

For the most part, however, I’m still using the Build Tablet in the docking station. The 
external keyboard, mouse, and monitor lets me run Visual Studio and Microsoft Word 
as rm accustomed to, while my Windows 8 programs run on the tablet’s touch screen. 
This is a fine development environment, particularly compared with the setup I used to 
write the first edition of Programming Windows. 

But that was 25 years ago. 


The Programming Windows Heritage 

This is the 6 th edition of Programming Windows, a book that was first conceived by 
Microsoft Press in the fall of 1986. The project came to involve me because at the time 
I was writing articles about Windows programming for Microsoft Systems Journal (the 
predecessor to MSDN Magazine). 

I still get a thrill when I look at my very first book contract: 



Introduction 


XXI 










Perhaps the most amusing part of this contract occurs further down the first page: 


n Manuscript 

The Author agrees to prepare and submit one (1) 
clean copy and one (1) ASCII readable diskette of the fi¬ 
nal manuscript of the Work, equivalent to approxi¬ 
mately 100»000 - words, not later than 

April 30, 1987 

" " 1 ， 

the due date. (A full manuscript page of text consists of 
approximately 250 words.) The Authors final man¬ 
uscript shall be in double-spaced typescript or its equiv¬ 
alent, satisfactory to the Publisher in organization, 
form, content, and style and accompanied by appropri¬ 
ate illustrative material, tabic of contents, tables, bibli¬ 
ography, and instructional aids ready for reproduction. 

The reference to "typescript" means that the pages must as least resemble something 
that came out of a typewriter. A double-spaced manuscript page with a fixed-pitch font 
has about 250 words, as the description indicates. A book page is more in the region of 
400 words, so Microsoft Press obviously wasn't expecting a very long book. 

For writing the book I used an IBM PC/AT with an 80286 microprocessor running 
at 8 MHz with 512 KB of memory and two 30 MB hard drives. The display was an IBM 
Enhanced Graphics Adapter, with a maximum resolution of 640x350 with 16 simultane¬ 
ous colors. I wrote some of the early chapters using Windows 1 (introduced over a year 
earlier in November 1985), but beta versions of Windows 2 soon became available. 

In those years, editing and compiling a Windows program occurred outside of 
Windows in MS-DOS. For editing source code, I used WordStar 3.3, the same word 
processor I used for writing the chapters. From the MS-DOS command line, you would 
run the Microsoft C compiler and then launch Windows with your program to test it 
out. It was necessary to exit Windows and return to MS-DOS for the next edit-compile- 
run cycle. 

As I got deeper into writing the book over the course of 1987, much of the rest of 
my life faded away. I stayed up later and later into the night. I didn’t have a television 
at the time, but the local public radio station, WNYC-FM, was on almost constantly with 
classical music and programming from National Public Radio. For a while, I managed 
to shift my day to such a degree that I went to bed after Morning Edition but awoke in 
time for >A// Things Considered. 

As the contract stipulated, I sent chapters to Microsoft Press on diskette and 
paper. (We all had email, of course, but email didn’t support attachments at the 
time.) The edited chapters came back to me by mail decorated with proofreading 
marks and numerous sticky notes. I remember a page on which someone had drawn 
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a thermometer indicating the increasing number of pages I was turning in with the 
caption "Temperature’s Rising!” 

Along the way, the focus of the book changed. Writing a book for "Programmers 
and Other Advanced Users” proved to be a flawed concept. I don’t know who came up 
with the title Programming Windows. 

The contract had a completion date of April, but I didn’t finish until August and the 
book wasn’t published until early 1988. The final page total was about 850. If these 
were normal book pages (that is, without program listings or diagrams) the word count 
would be about 400,000 rather than the 100,000 indicated in the contract. 

The cover of the first edition of Programming Windows described it as "The 
Microsoft Guide to Programming for the MS-DOS Presentation Manager: Windows 
2.0 and Windows/386." The reference to Presentation Manager reminds us of the days 
when Windows and the OS/2 Presentation Manager were supposed to peacefully 
coexist as similar environments for two different operating systems. 

The first edition of Programming Windows went pretty much unnoticed by the 
programming community. When MS-DOS programmers gradually realized they needed 
to learn about the brave new environment of Windows, it was mostly the 2 nd edition 
(published in 1990 and focusing on Windows 3) and the 3 rd edition (1992, Windows 3.1) 
that helped out. 

When the Windows API graduated from 16-bit to 32-bit, Programming Windows 
responded with the 4 th edition (1996, Windows 95) and 5 th edition (1998, Windows 
98). Although the 5 th edition is still in print, the email I receive from current readers 
indicates that the book is most popular in India and China. 

From the 1 st edition to the 5 th , I used the C programming language. Sometime 
between the 3 rd and 4 th editions, my good friend Jeff Prosise said that he wanted to 
write Programming Windows with MFC, and that was fine by me. I didn’t much care for 
the Microsoft Foundation Classes, which seemed to me a fairly light wrapper on the 
Windows API, and I wasn't that thrilled with C++ either. 

As the years went by, Programming Windows acquired the reputation of being the 
book for programmers who needed to get close to the metal without any extraneous 
obstacles between their program code and the operating system. 

But to me, the early editions of Programming Windows were nothing of the sort. In 
those days, getting close to the metal involved coding in assembly language, writing 
character output directly into video display memory, and resorting to MS-DOS only 
for file I/O. In contrast, programming for Windows involved a high-level language, 
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completely unaccelerated graphics, and accessing hardware only through a heavy layer 
of APIs and device drivers. 


This switch from MS-DOS to Windows represented a deliberate forfeit of speed 
and efficiency in return for other advantages. But what advantages? Many veteran 
programmers just couldn’t see the point. Graphics? Pictures? Color? Fancy fonts? A 
mouse? That’s not what computers are all about! The skeptics called it the WIMP 
(window-icon-menu-pointer) interface, which was not exactly a subtle implication 
about the people who chose to use such an environment or code for it. 

If you wait long enough, a high-level language becomes a low-level language, 
and multiple layers of interface seemingly shrink down (at least in lingo) to a native 
API. Some C and C++ programmers of today reject a managed language like C# on 
grounds of efficiency, and Windows has even sparked some energetic controversy 
once again. Windows 8 is easily the most revolutionary updating to Windows since its 
very first release in 1985, but many old-time Windows users are wondering about the 
wisdom of bringing a touch-based interface tailored for smartphones and tablets to the 
mainstream desktop, and they grumble when they can’t find familiar features. 

I suppose that Programming Windows could only be persuaded to emerge from 
semi-retirement with an exciting and controversial new user interface on Windows, and 
an API and programming language suited to its modern aspirations. 

More in the Future 


I suspect that Windows 8 will dominate my programming life for a while, which 
means that I’m likely to be posting blog entries about various aspects of Windows 8 
programming. You can access my blog and subscribe to the RSS feed at 
www.charlespetzold.com. 

I always enjoy solving a thorny programming problem and posting a blog entry 
about it, so if you have a Windows 8 programming issue that you’d like me to take a 
look at and possibly figure out, write me at cp@chorlespetzold.com. 


Beginning with the January 2013 issue of MSDN Magazine, \ will be writing a 
monthly column called "DirectX Factor," focusing specifically on using DirectX from 
Windows 8 and Windows Phone 8 applications. MSDN Magazine is available for free 
perusal at http://msdn.microsoft.com/magazine. 
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CHAPTER 1 

Markup and Code 


E ver since the publication of Brian Kernighan and Dennis Ritchie’s classic book The C Programming 
Language (Prentice Hall, 1978), it has been customary for programming tutorials to begin with 
a simple program that displays a short text string such as "hello, world.’’ Let’s create a few similar 
programs for the new world of Windows 8. 

Ill assume you have Windows 8 installed as well as a recent version of Microsoft Visual Studio that 
supports the creation of Windows 8 applications. 

Launch Visual Studio from the Windows 8 start screen, and let’s get coding. 


The First Project 


On the opening screen in Visual Studio, the Get Started tab should already be selected. Over at the 
left you'll see a New Project option. Click that item, or select New Project from the File menu. 

When the New Project dialog box opens, select Templates in the left panel, then Visual C#, and the 
option for creating a new Windows Store project. From the list of available templates in the central 
area, select Blank App. Toward the bottom of the dialog box, type a project name in the Name field: 
Hello, for example. Let the Solution Name be the same. Use the Browse button to select a directory 
location for this program, and click OK. (Ill generally use mouse terminology such as "click” when re¬ 
ferring to Visual Studio, but I’ll switch to touch terminology such as "tap" for the applications you’ll be 
creating. A version of Visual Studio that is optimized for touch is probably at least a few years away.) 

Visual Studio creates a solution named Hello and a project within that solution named Hello, as 
well as a bunch of files in the Hello project. These files are listed in the Solution Explorer on the far 
right of the Visual Studio screen. Every Visual Studio solution has at least one project, but a solution 
might contain additional application projects and library projects. 
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The list of files for this project includes one called MainPage.xaml, and if you click the little 
arrowhead next to that file, you’ll see a file named MainPage.xaml.es indented underneath 
MainPage.xaml: 


Solution Explorer 

▼平 X 

^ T o ， ^ _ 1) <> A 


Search Solution Explorer (Ctrl+;) 

P- 

Solution 'Hello' (1 project) 


a [c#] Hello 


> Properties 


> References 


> Assets 


> 篇 Common 


> .D Appjcaml 


SH3 Hello_TemporaryKey.pfx 


J MainPage.xaml 

> MainPage.xaml.cs 


1^1 Package.appxmanifest 



You can view either of these two files by double-clicking the file name or by right-clicking the file 
name and choosing Open. 


The MainPage.xaml and MainPage.xaml.es files are linked in the Solution Explorer because they 
both contribute to the definition of a class named MainPage. For a simple program like Hello, this 
MainPage class defines all the visuals and user interface for the application. 

Despite its funny file name, MainPage.xaml.es definitely has a .cs extension, which stands for 
"C Sharp." Stripped of all its comments, the skeleton MainPage.xaml.es file contains C# code that looks 
like this: 

using System; 

using System.Col 1ections.Generic; 

using System.10; 

using System.Linq; 

using Windows.Foundation; 

using Windows.Foundation.Col 1ections; 

using Windows.UI.Xaml; 

using Windows.UI.Xaml.Controls; 

using Windows.UI.Xaml.Controls.Primitives; 

using Windows.UI.Xaml.Data; 

using Windows.UI.Xaml.Input; 

using Windows.UI.Xaml.Medi a; 

using Windows.UI.Xaml.Navigation; 

namespace Hello 

{ 

public sealed partial cl ass MainPage : Page 

{ 

public MainPageO 

{ 
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thi s .InitializeComponent(); 


} 

protected override void OnNavigatedTo(Navi gationEventArgs e) 
{ 

} 


The file is dominated by using directives for all the namespaces that you are anticipated to need. 
You’ll discover that most MainPage.xaml.es files don’t require all these namespaces and many others 
require some additional namespaces. 

These namespaces fall into two general categories based on the first word in the name: 

■ System * .NET for new Windows 8 applications 

■ Windows* Windows Runtime (or WinRT) 

As suggested by the list of using directives, namespaces that begin with Windows.Ul.Xoml play a 
major role in the Windows Runtime. 

Following the using directives, this MainPage.xaml.es file defines a namespace named Hello (the 
same as the project name) and a class named MoinPoge that derives from Page, a class that is part of 
the Windows Runtime. 

The documentation of the Windows 8 API is organized by namespace, so if you want to locate the 
documentation of the Page class, knowing the namespace where it’s defined is useful. Let the mouse 
pointer rest on the name Page in the MainPage.xaml.es source code, and you’ll discover that Page is in 
the Windows.Ul.Xaml.Controls namespace. 


The constructor of the MainPage class calls an InitiolizeComponent method (which 111 discuss 
shortly), and the class also contains an override of a method named OnNavigatedTo. Windows 
8 applications often have a page-navigation structure somewhat like a website, and hence they 
often consist of multiple classes that derive from Page. For navigational purposes, Page defines 
virtual methods named On No vigating From, OnNavigotedFrom, and OnNavigatedTo. The override of 
OnNavigatedTo is a convenient place to perform initialization when the page becomes active. But 
that’s for later; most of the programs in the early chapters of this book will have only one page. I’ll 
tend to refer to an application’s "page" more than its "window." There is still a window underneath the 
application, but it doesn’t play nearly as large a role as the page. 

Notice the partial keyword on the MainPage class definition. This keyword usually means that the 
class definition is continued in another C# source code file. In reality (as you'll see), that's exactly the case. 
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Conceptually, however, the missing part of the Main Page class is not another C# code file but the 
MainPage.xaml file: 


<Page 

x : Class=" Hello.MainPage" 

xml ns="http: //schemas.microsoft.com/winfx/2006/xaml/presentation" 
xml ns : x="http: //schemas.microsoft.com/winfx/2006/xaml" 
xml ns : 1ocal ="using : He! lo" 

xml ns : d="http: //schemas.microsoft.com/expression/blend/2008" 

xml ns : mc="http : //schemas.openxmlformats.org/markup-compatibi1ity/2006" 

me : Ignorabl e="d"> 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 


</Gri d> 

</Page> 

This file consists of markup conforming to the standard known as the extensible Application Markup 
Language, or XAML, pronounced "zammel." As the name implies, XAML is based on extensible 
Markup Language, or XML. 


Generally, you’ll use the XAML file for defining all the visual elements of the page, while the C# file 
handles jobs that can’t be performed in markup, such as number crunching and responding to user 
input. The C# file is often referred to as the "code-behind" file for the corresponding XAML file. 

The root element of this XAML file is Page, which you already know is a class in the Windows 
Runtime. But notice the x:Closs attribute: 


<Page 

x:Class="Hello.Mai nPage" 

The x:Class attribute can appear only on the root element in a XAML file. This particular x:Closs 
attribute translates as "a class named MoinPoge in the Hello namespace is defined as deriving from 
Page." It means the same thing as the class definition in the C# file! 


Following that are a bunch of XML namespace declarations. As usual, these URls don’t actu¬ 
ally reference interesting webpages but instead serve as unique identifiers maintained by particular 
companies or organizations. The first two are the most important: 

xml ns="http: //schemas.microsoft.com/winfx/2006/xaml/presentation" 
xml ns : x="http: //schemas.microsoft.com/winfx/2006/xaml" 

The 2006 date harkens back to Microsoft’s introduction of the Windows Presentation Foundation 
and the debut of XAML. WPF was part of the .NET Framework 3.0, which prior to its release was 
known as WinFX, hence the "winfx” in the URL To a certain extent, XAML files are compatible among 
WPF, Silverlight, Windows Phone, and the Windows Runtime, but only if they use classes, properties, 
and features common to all the environments. 


The first namespace declaration with no prefix refers to public classes, structures, and 
enumerations defined in the Windows Runtime, which includes all the controls and everything else 
that can appear in a XAML file, including the Page and Grid classes in this particular file. The word 
"presentation” in this URI refers to a visual user interface, and that distinguishes it from other types 
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of applications that can use XAML. For example, if you were using XAML for the Windows Workflow 
Foundation (WF), you'd use a default namespace URI ending with the word "workflow." 

The second namespace declaration associates an 〃 x” prefix with elements and attributes that 
are intrinsic to XAML itself. Only nine of these are applicable in Windows Runtime applications, and 
obviously one of the most important is the x: Cl ass attribute. 

The third namespace declaration is interesting: 
xml ns : local="usi ng : Hello" 

This associates an XML prefix of local with the Hello namespace of this particular application. You 
might create custom classes in your application, and you’d use the local prefix to reference them 
in XAML. If you need to reference classes in code libraries, you’ll define additional XML namespace 
declarations that refer to the assembly name and namespace name of these libraries. You’ll see how 
to do this in chapters ahead. 

The remaining namespace declarations are for Microsoft Expression Blend. Expression Blend 
might insert special markup of its own that should be ignored by the Visual Studio compiler, so that’s 
the reason for the Ignoroble attribute, which requires yet another namespace declaration. For any 
program in this book, these last three lines of the Page root element can be deleted. 


The Page element has a child element named Grid, which is another class defined in the 
VJindows.ULXaml.Controls namespace. The Grid will become extremely familiar. It is sometimes 
referred to as a "container” because it can contain other visual objects, but it’s more formally classified 
as a "panel” because it derives from the Panel class. Classes that derive from Panel play a very impor¬ 
tant role in layout in Windows 8 applications. In the MainPage.xaml file that Visual Studio creates for 
you, the Grid is assigned a background color (actually a Brush object) based on a predefined identifier 
using a syntax I’ll discuss in Chapter 2, "XAML Syntax.’’ 

Generally, you’ll divide a Grid into rows and columns to define individual cells (as I’ll demonstrate 
in Chapter 5, "Control Interaction”)，somewhat like a much improved version of an HTML table. A Grid 
without rows and columns is sometimes called a "single-cell Grid" and is still quite useful. 


To display up to a paragraph of text in the Windows Runtime, you’ll generally use a TextBlock 
(another class defined in the Windows.Ul.Xoml.Controls namespace), so let’s put a TextBlock in the 
single-cell Grid and assign a bunch of attributes. These attributes are actually properties defined by 
the TextBlock class: 


Project: Hello I File: MainPage.xaml (excerpt) 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
〈TextBlock Text="Hello, Windows 8!" 

FontFami1 y="Ti mes New Roman" 

FontSize="96" 

FontStyl e="Ital ic" 

Foreground="Yellow" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Center" /> 

</Grid> 
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Note In this book, whenever a block of code or markup is preceded by a heading like this 
one, you’ll find the code among this book’s downloadable companion content. Generally, 
I’ll just show an excerpt of the total file but with enough context so that you know exactly 
where it is. 


The order of these attributes doesn't matter, and of course the indentation doesn't matter, and 
all of them except the Text attribute can be skipped if you’re in a hurry. As you type you’ll notice that 
Visual Studio’s IntelliSense feature suggests attribute names and possible values for you. Often you 
can just select the one you want. As you finish typing the TextBlock, Visual Studio’s design view gives 
you a preview of the page’s appearance. 

You can also skip all the typing and simply drag a TextBlock from the Visual Studio Toolbox 
and then set the properties in a table, but I won't be doing that in this book. I’ll instead describe 
the creation of these programs as if you and I actually type in the code and markup just like real 
programmers. 

Press F5 to compile and run this program, or select Start Debugging from the Debug menu. Even 
for simple programs like this, it’s best to run the program under the Visual Studio debugger. If all goes 
well, this is what you’ll see: 


Hello, Windows 8! 


The Horizontal Alignment and VerticalAlignment attributes on the TextBlock have caused the text to 
be centered, obviously without the need for you the programmer to explicitly determine the size of 
the video display and the size of the rendered text. You can alternatively set HorizontalAlignment to 
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Left or Right, and VerticolAlignment to Top or Bottom to position the Text Block in one of nine places in 
the Grid. As you’ll see in Chapter 4, "Presentation with Panels," the Windows Runtime supports precise 
pixel placement of visual objects, but usually you’ll want to rely on the built-in layout features. 

The TextBlock has Width and Height properties, but generally you don’t need to bother setting 
those. In fact, if you set the Width and Height properties on this particular TextBlock, you might end 
up cropping part of the text or interfering with the centering of the text on the page. The TextBlock 
knows better than you how large it should be. 

You might be running this program on a device that responds to orientation changes, such as a 
tablet. If so, you’ll notice that the page content dynamically conforms to the change in orientation 
and aspect ratio, apparently without any interaction from the program. The Grid, the TextBlock, and 
the Windows 8 layout system are doing most of the work. 


To terminate the Hello program, press Shift+F5 in Visual Studio, or select Stop Debugging from 
the Debug menu. You’ll notice that the program hasn't merely been executed, but has actually been 
deployed to Windows 8 and is now executable from the start screen. If you’ve created the project 
yourself, the tile is not very pretty, but the program’s tiles are all stored in the Assets directory of the 
project, so you can spruce them up if you want. (The projects in the downloadable companion con¬ 
tent for this book have been given custom tiles.) You can run the program again outside of the Visual 
Studio debugger right from the Windows 8 start screen. 

Another option is to run your programs in a simulator that lets you control resolution, orientation, 
and other characteristics. In the Visual Studio toolbar, you’ll see a drop-down list with the current 
setting Local Machine. Simply change that to Simulator. 


Graphical Greetings 

Traditional "hello" programs display a greeting in text, but that's not the only way to do it. The 
Hellolmage project accesses a bitmap from my website using a tiny piece of XAML: 


Project: Hellolmage I File: MainPage.xaml (excerpt) 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Image Source="http://www.charl espetzold.com/pw6/Petzold3ersey.jpg" /> 
</Grid> 
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The Image element is defined in the Windows.Ul.Xaml.Controls namespace, and it's the standard 
way to display bitmaps in a Windows Runtime program. By default, the bitmap is stretched to fit the 
space available for it while respecting the original aspect ratio: 



If you make the page smaller — perhaps by changing the orientation or invoking a snap view — the 
image will change size to accommodate the new size of the page. 

You can override the default display of this bitmap by using the Stretch property defined by Image. 
The default value is the enumeration member Stretch.Uniform. Try setting it to Fill: 

<Crid Background:" {StaticResource ApplicationPageBackgroundThemeBrush}"> 

<Image Sou rce="http: //www.charlespetzold.com/pw6/PetzoldJersey.jpg" 

Stretch= n Fill" /> 

</Crid> 
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Now the aspect ratio is ignored and the bitmap fills the container: 



Set the Stretch property to None to display the image in its pixel dimensions (320 by 400): 



You can control where it appears on the page by using the same HorizontolAlignment and 
Vertical A lign ment properties you use with TextBlock. 

The fourth option for the Stretch property is UniformToFill, which respects the aspect ratio but fills 
the container regardless. It achieves this feat by the only way possible: clipping the image. Which part 
of the image that gets clipped depends on the HorizontolAlignment and Vertical A lign men t properties. 
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Accessing bitmaps over the Internet is dependent on a network connection and even then might 
require some time. A better guarantee of having an image immediately available is to bind the 
bitmap into the application itself. 

You can create simple bitmaps right in Windows Paint. Let’s run Paint and use the File Properties 
option to set a size of 480 by 320 (for example). Using a mouse, finger, or pen, you can create your 
own personalized greeting: 



The Windows Runtime supports the popular BMP, JPEG, PNG, and GIF formats, as well as a couple less 
common formats. For images such as the preceding one, PNG is common, so save it with a name like 
Greeting.png. 

Now create a new project: HelloLocallmage, for example. It’s common to store bitmaps used by a 
project in a directory named Images. In the Solution Explorer, right-click the project name and choose 
Add and New Folder. (Or, if the project is selected in the Solution Explorer, pick New Folder from the 
Project menu.) Give the folder a name such as Images. 

Now right-click the Images folder and choose Add and Existing Item. Navigate to the Greeting.png 
file you saved and click the Add button. Once the file is added to the project, you’ll want to right-click 
the Greeting.png file name and select Properties. In the Properties panel, make sure the Build Action 
is set to Content. You want this image to become part of the content of the application. 

The XAML file that references this image looks very much like one for accessing an image over the 
web: 


Project: HelloLocallmage I File: MainPage.xaml (excerpt) 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Image Source="Images/Greeti ng.png" 

Stretch="None" /> 

</Grid> 
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Notice that the Source property is set to the folder and file name. Here's how it looks: 



Sometimes programmers prefer giving a name of Assets to the folder that stores application 
bitmaps. You’ll notice that the standard project already contains an Assets folder containing program 
logo bitmaps. You can use that same folder for your other images instead of creating a separate 
folder. 


Variations in Text 


You might be tempted to refer to the Grid, TextBlock, and Image as "controls," perhaps based on 
the knowledge that these classes are in the Windows.Ul.Xoml.Controls namespace. Strictly speaking, 
however, they are not controls. The Windows Runtime does define a class named Control, but these 
three classes do not descend from Control. Here’s a tiny piece of the Windows Runtime class hierarchy 
showing the classes encountered so far: 

Object 

DependencyObject 
UlElement 
FrameworkElement 
Text Block 
Image 
Panel 
Grid 
Control 
User Control 
Page 
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Page derives from Control but TextBlock and Image do not TextBlock and Image instead derive from 
UlElement and FrameworkElement. For that reason, TextBlock and Image are more correctly referred 
to as "elements," the same word often used to describe items that appear in XML files. 

The distinction between an element and a control is not always obvious, but the distinction is 
useful nonetheless. Visually, controls are built from elements, and the visual appearance of the control 
can be customizable through a template. A Grid is also an element, but it’s more often referred to as a 
"panel,” and that (as you’ll see) is a very useful distinction. 

Try this: In the original Hello program move the Foreground attribute and all the font-related 
attributes from the TextBlock element to the Page. The entire MainPage.xaml file now looks like this: 

<Page 

x:Class="Hello.Mai nPage" 

xml ns="http: //schemas.microsoft.com/winfx/2006/xaml/presentation" 
xml ns : x="http: //schemas.microsoft.com/winfx/2006/xaml" 
xml ns:local=" using:Hello" 

xml ns : d="http: //schemas.microsoft.com/expression/blend/2008" 

xml ns : mc="http: //schemas.openxmlformats.org/markup-compatibi1ity/2006" 

mc:Ignorable="d" 

FontFami1 y="Ti mes New Roman" 

FontSize="96" 

FontStyl e="Ital ic" 

Foreground="Yel low"> 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

〈TextBlock Text="Hello, Windows 8!" 

HorizontalAli gnment="Center" 

VerticalA1i gnment="Center" /> 

</Gri d> 

</Page> 

You'll discover that the result is exactly the same. When these attributes are set on the Page element, 
they apply to everything on that page. 

Now try setting the Foreground property of the TextBlock to red: 

〈TextBlock Text="Hello, Windows 8!" 

Foreground="Red" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Center" /> 

The local red setting overrides the yellow setting on the Page. 

The Page, Grid, and TextBlock form what is called a "visual tree" of elements, except that in the 
XAML file the tree is upside-down. The Page is the trunk of the tree, and its descendants {Grid and 
TextBlock) form branches. You might imagine that the values of the font properties and Foreground 
property defined on the Page are propagated down through the visual tree from parent to child. This 
is true except for a little peculiarity: These properties don’t exist in Grid. These properties are defined 
by TextBlock and separately defined by Control, which means that the properties manage to propa¬ 
gate from the Page to the TextBlock despite an intervening element that has very different DNA. 
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If you begin examining the documentation of these properties in the TextBlock or Page class, you'll 
discover that they seem to appear twice under somewhat different names. In the documentation of 
TextBlock you'll see a Font Size property of type double: 

public double FontSize { set; get; } 

You’ll also see a property named FontSizeProperty of type Dependency Property: 

public static DependencyProperty FontSizeProperty { get; } 

Notice that this FontSizeProperty property is get-only and static as well. 

Many of the classes that you’ll use in constructing the user interface of a Windows 8 application 
have conventional properties as well as corresponding properties called "dependency properties” 
of type Dependency Property. Interestingly enough, the class hierarchy I just showed you has a class 
named DependencyObject. These two types are related: A class that derives from DependencyObject 
often declares static get-only properties of type DependencyProperty. Both DependencyObject and 
Dependency Property are defined in the Windows. Ul.Xoml namespace, suggesting how fundamental 
they are to the whole system. 


Dependency properties are intended to solve some fundamental problems that come about in 
sophisticated user interfaces. In a Windows 8 application, properties can be set in a variety of ways. 
For example, you’ve already seen that properties can be set directly on an object or inherited through 
the visual tree. As you’ll see in Chapter 2, "XAML Syntax," properties might also be set from a Style 
definition. In a future chapter you’ll see properties set from animations. The DependencyObject and 
DependencyProperty classes are part of a system that helps maintain order in such an environment by 
establishing priorities for the different ways in which the property might be set. I don't want to go too 
deeply into the mechanism just yet; it’s something you’ll experience more intimately when you begin 
defining your own controls. 

The FontSize property is sometimes said to be "backed by" the dependency property named 
FontSizeProperty. But sometimes a semantic shortcut is used and FontSize itself is referred to as a 
dependency property. Usually this is not confusing. 

Many of the properties defined by UlElement and its descendent classes are dependency 
properties, but only a few of these properties are propagated through the visual tree. Foreground and 
all the font-related properties are, as well as a few others that I’ll be sure to call your attention to as 
we encounter them. Dependency properties also have an intrinsic default value. If you remove all the 
TextBlock and Page attributes except Text, you’ll get white text displayed with an 11-pixel system font 
in the upper-left corner of the page. 

The FontSize property is in units of pixels and refers to the design height of a font. This design 
height includes space for descenders and diacritical marks. As you might know, font sizes are often 
specified in points, which in electronic typography are units of 1/72 inch. The equivalence between 
pixels and points requires knowing the resolution of the video display in dots-per-inch (DPI). Without 
that information, it’s generally assumed that video displays have a resolution of 96 DPI, so a 96-pixel 
font is thus a 72-point font (one-inch high) and the default 11-pixel font is an 8%-point font. 
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For high-resolution displays, Windows automatically adjusts sizes and coordinates. An application 
can obtain this information from the DisplayProperties class, which pretty much dominates the 
Windows.Graphics.Display namespace. For most purposes, however, assuming a resolution of 96 DPI 
is fine, and you’ll use this same assumption for the printer. In accordance with this assumption, I tend 
to use pixel dimensions that represent simple fractions of inches: 48 (l/2〃)，24 (l/4〃)，12 {1/S"), and 
6 (1/16〃). 

You’ve seen that if you remove the Foreground attribute, you get white text on a dark background. 
The background is not exactly black, but the predefined ApplicationPageBackgroundThemeBrush 
identifier that the Grid references is close to it. 

The Hello project also includes two other files that come in a pair: App.xaml and App.xaml.es 
together define a class named App that derives from Application. Although an application can have 
multiple Page derivatives, it has only one Application derivative. This App class is responsible for 
settings or activities that affect the application as a whole. 

Try this: In the root element of the App.xaml file, set the attribute RequestedTheme to Light. 

<Applicati on 

x:Cl ass="Hell o.App" 

xml ns="http: //schemas.microsoft.com/winfx/2006/xaml/presentation" 
xml ns : x="http: //schemas.microsoft.com/winfx/2006/xaml" 
xml ns:local=" using:Hello" 

RequestedTheme="Li ght"> 

</Application> 

The only options are Light and Dark. Now when you recompile and run the program, it has a light 
background, which means the color referenced by the Application PageBackgroundThemeBrush identi¬ 
fier is different. If the Foreground property on the Page or TextBlock is not explicitly set, you’ll also get 
black text, which means that the Foreground property has a different default value with this theme. 

In many of the sample programs in the remainder of this book, I’ll be using the light theme with¬ 
out mentioning it. I think the screen shots look better on the page, and they won’t consume as much 
ink if you decide to print pages from the book. However, keep in mind that many small devices and 
an increasing number of larger devices have video displays built around organic light-emitting diode 
(OLED) technology and these displays consume less power if the screen isn’t lit up like a billboard. 
Reduced power consumption is one reason why dark color schemes are becoming more popular. 

Of course, you can completely specify your own colors by explicitly setting both the Background of 
the Grid and the Foreground of the TextBlock: 

〈Grid Background="Bl ue"> 

<TextBlock Text="Hello, Windows 8!" 

Foreground="Yel low" 

... /> 

</Grid> 
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For these properties, Visual Studio’s IntelliSense provides 140 standard color names, plus Transparent. 
These are actually static properties of the Colors class. Alternatively, you can specify red-green-blue 
(RGB) values directly in hexadecimal with values ranging from 00 to FF prefaced by a pound sign: 

Foreground="#FF8000" 

That’s maximum red, half green, and no blue. An optional fourth byte at the beginning is the alpha 
channel, with values ranging from 00 for transparent and FF for opaque. Here’s a half-transparent red: 

Foreground="#80FF0000" 

When an alpha value is included at the beginning, these are sometimes referred to as ARGB colors. 
The UlElement class also defines an Opacity property that can be set to values between 0 (transpar¬ 
ent) and 1 (opaque). In Hellolmage, try setting the Background property of the Grid to a nonblack 
color (perhaps Blue) and set the Opacity property of the Image element to 0.5. 

When you specify colors by using bytes, the values are in accordance with the familiar sRGB 
("standard RGB”）color space. This color space dates back to the era of cathode-ray tube displays 
where these bytes directly controlled the voltages illuminating the pixels. Very fortuitously, nonlinear¬ 
ities in pixel brightness and nonlinearities in the perception of brightness by the human eye roughly 
cancel each other out, so these byte values often seem perceptually linear, or nearly so. 

An alternative is the scRGB color space, which uses values between 0 and 1 that are proportional to 
light intensity. Here’s a value for medium gray: 

Foreground="sc# 0.5 0.5 0.5" 

Because of the logarithmic response of the human eye to light intensity, this gray will appear to be 
rather too light to be classified as medium. 

If you need to display text characters that are not on your keyboard, you can specify them in 
Unicode by using standard XML character escaping. For example, if you want to display the text "This 
costs €55 〃 and you’re confined to an American keyboard, you can specify the Unicode Euro in decimal 
like this: 

〈TextBlock Text="Thi s costs &#8364;55" ... 

Or perhaps you prefer hexadecimal: 

〈TextBlock Text="Thi s costs Mx20AC;55" ... 

Or you can simply paste text into Visual Studio as I obviously did with a program later in this chapter. 
As with standard XML, strings can contain special characters beginning with the ampersand: 

■ &amp; is an ampersand 

■ &apos; is a single-quotation mark ("apostrophe ”） 

■ &quot; is a double-quotation mark 
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&lt; is a left angle bracket ("less than") 

&gt; is a right angle bracket ("greater than") 


An alternative to setting the Text property of TextBlock requires separating the element into a start 
tag and end tag and specifying the text as content: 

<TextBlock … > 

Hello, Windows 8! 

</TextBlock> 


As I’ll discuss in Chapter 2, setting text as content of the TextBlock is not exactly equivalent to 
setting the Text property. It’s actually much more powerful. But even without taking advantage of 
additional features, specifying text as content is useful for displaying a larger quantity of text because 
you don’t have to worry about extraneous white space as much as when you’re dealing with quoted 
text. The WrappedText project displays a whole paragraph of text by specifying this text as content of 
the TextBlock: 


Project: WrappedText I File: MainPage.xaml (excerpt) 

<Crid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
〈TextBlock FontSi ze="48" 

TextWrappi ng="Wrap"> 

For a long time I used to go to bed early. Sometimes, when I had put out 
my candle, my eyes would close so quickly that I had not even time to 
say "I’m going to sleep." And half an hour later the thought that it was 
time to go to sleep would awaken me; I would try to put away the book 
which, I imagined ， was still in my hands, and to blow out the light; I 
had been thinking all the time ， while I was asleep, of what I had just 
been reading ， but my thoughts had run into a channel of their own, 
until I myself seemed actually to have become the subject of my book: 
a church, a quartet, the rivalry between Frangois I and Charles V. This 
impression would persist for some moments after I was awake; it did not 
disturb my mind ， but it lay like scales upon my eyes and prevented them 
from registering the fact that the candle was no longer burning. Then 
it would begin to seem unintel1igible, as the thoughts of a former 
existence must be to a reincarnate spirit; the subject of my book would 
separate itself from me, leaving me free to choose whether I would form 
part of it or no; and at the same time my sight would return and I 
would be astonished to find myself in a state of darkness, pleasant and 
restful enough for the eyes, and even more, perhaps, for my mind, to 
which it appeared incomprehensible, without a cause, a matter dark 
indeed. 

</TextBlock> 

</Grid> 


When parsed, the end-of-line characters at the end of each line and the eight space characters at the 
beginning of each line are collapsed into a single space character. 

Notice the TextWropping property. The default is the TextWrapping.NoWrap enumeration 
member; Wrap is the only alternative. You can also set the TextAlignment property to members of 
the TextAlignment enumeration: Left, Right, Center, or Justify, which causes extra space to be inserted 
between words so that the text is even on both the left and right. 
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You can run this program in either portrait mode or landscape: 

For a long time I used to go to bed early. Sometimes, when I 
had put out my candle, my eyes would close so quickly that I 
had not even time to say "I'm going to sleep." And half an hour 
later the thought that it was time to go to sleep would awaken 
me; I would try to put away the book which, I imagined, was still 
in my hands, and to blow out the light; I had been thinking all 
the time, while I was asleep, of what I had just been reading, but 
my thoughts had run into a channel of their own, until I myself 
seemed actually to have become the subject of my book: a 
church, a quartet, the rivalry between Frangois I and Charles V. 
This impression would persist for some moments after I was 
awake; it did not disturb my mind, but it lay like scales upon my 
eyes and prevented them from registering the fact that the 


If your display responds to orientation changes, the text is automatically reformatted. The Windows 
Runtime breaks lines at spaces or hyphens, but it does not break lines at nonbreaking spaces 
( , &#x00A0 , ) or nonbreaking hyphens C&#x20ir). Any soft hyphens ( , &#xOOAD , ) are ignored. 

Not every element in XAML supports text content like TextBlock. You can’t have text content in the 
Page or Grid, for example. XAML is not as free form as HTML because XAML syntax is based entirely 
on underlying classes and properties. 

But the Grid can support multiple TextBlock children. The OverlappedStackedText project has two 
TextBlock elements in the Grid with different colors and font sizes: 


Project: OverlappedStackedText | File: MainPage.xaml 

〈Grid Background="Yel low"> 

〈TextBlock Text="8" 

FontSize="864" 

FontWei ght="Bold" 

Foreground:" Red 11 

HorizontalAli gnment="Center" 

VerticalAli gnment="Center" /> 

〈TextBlock Text="Wi ndows" 

FontSize="192" 

FontStyl e="Ital ic" 
Foreground="Bl ue" 

HorizontalAli gnment="Center" 
VerticalAli gnment="Center" /> 

</Grid> 
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Here’s the result: 



Notice that the second element is visually above the first. This visual stacking is often referred to as 
〃Z order” because in a three-dimensional coordinate space, an imaginary Z axis comes out of the 
screen. In Chapter 4 you’ll see a way to override this behavior. 

Of course, overlapping is not a generalized solution to displaying multiple items of text! 

In Chapter 5 you’ll see how to define rows and columns in the Grid for layout purposes, but 
another approach to organizing multiple elements in a single-cell Grid is to use various val¬ 
ues of Horizon to I A lignment and VerticolAlignment to prevent them from overlapping. The 
InternationalHelloWorld program displays "hello, world" in nine different languages. (Thank you, 
Google Translate.) 

Project: InternationalHelloWorld | File: MainPage.xaml (excerpt) 

<Page 

x:Cl ass="Internati onalHelloWorld.MainPage" 

FontSi ze="40"> 


<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<!-- Chinese (simplified)--> 

<TextBlock Text= " 你好，世界 " 

Hori zontalAli gnment="Left" 

VerticalA1i gnment="Top" /> 

<!-- Urdu --> 

〈TextBlock Text='VJ”c^‘" 

HorizontalAli gnment="Center" 

VerticalA1i gnment="Top" /> 
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<!-- Japanese --> 

<TextBlock Text= n 二 K 二它 (i 、 世界中 

HorizontalAli gnment="Ri ght" 
VerticalAli gnment="Top" /> 

<!-- Hebrew --> 

cTextBlock Text='V?iD, 

HorizontalAli gnment="Left" 
VerticalAli gnment="Center" /> 

<!-- Esperanto --> 

<TextBlock Text="Sal uton, mondo" 

HorizontalAli gnment="Center" 
VerticalAl ignment="Center" /> 

<!-- Arabic --> 

<TextBlock Text=" fJ r^u 

HorizontalAli gnment="Ri ght" 
VerticalAl ignment="Center" /> 

<!-- Korean --> 

〈TextBlock Text=" 社 4 斜砷 •，苟 乂 W' 

HorizontalAli gnment="Left" 
VerticalAl ignment="Bottom" /> 

<!-- Russian --> 

<TextBlock Text=''3flpaBCTBy 卩， Mnp" 

HorizontalAli gnment="Center" 
VerticalAli gnment="Bottom" /> 

<!-- Hindi --> 

<TextBlock Text="^TfRTrT t ," 

HorizontalAli gnment="Ri ght" 
VerticalAli gnment="Bottom" /> 

</Grid> 

</Page> 


Notice the Font Size attribute set in the root element to apply to all nine TextBlock elements. Property 
inheritance is obviously one way to reduce repetition in XAML, and you’ll see other approaches as 
well in the next chapter. 
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你好，世界 


3-U 1 * 


乙九([5(才、世界中 ® 办九 


Dbi\j ,Dibw 


Saluton, mondo 



2 A1|7|| 


3ApaBCTByM, MMp 


^FRcl^TTt, 


Media As Wei 


So far you’ve seen greetings in text and bitmaps. The HelloAudio project plays an audio greeting from 
a file on my website. I made the recording using the Windows 8 Sound Recorder application, which 
automatically saves in WMA format. The XAML file looks like this: 

Project: HelloAudio | File: MainPage.xaml (excerpt) 

<Grid Background:'' {StaticResource ApplicationPageBackgroundThemeBrush}"> 

<MediaElement Source="http: //www.charlespetzold.com/pw6/AudioGreeting.wma" /> 

</Grid> 

The MecJiaElement class derives from FmmeworkElement and has no user interface, although it 
provides enough information for you to build your own. 

You can also use MediaElement for playing movies. The HelloVideo program plays a video from my 
website: 

Project: HelloVideo | File: MainPage.xaml (excerpt) 

<Grid Background=” {StaticResource ApplicationPageBackgroundThemeBrush}"> 

<MediaElement Source="http: //www.charlespetzold.com/pw6/VideoGreeting.wmv" /> 

</Grid> 
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The Code Alternatives 


It’s not necessary to instantiate elements or controls in XAML. You can alternatively create them 
entirely in code. Indeed, very much of what can be done in XAML can be done in code instead. Code 
is particularly useful for creating many objects of the same type because there’s no such thing as a for 
loop in XAML 

Let’s create a new project named HelloCode, but let’s visit the MainPage.xaml file only long 
enough to give the Grid a name: 

Project: HelloCode I File: MainPage.xaml (excerpt) 

<Grid Name="contentGri d" 

Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

</Grid> 


Setting the Name attribute allows the Grid to be accessed from the code-behind file. Alternatively, 
you can use x:Name: 

<Grid x : Name="contentGri d" 

Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

</Grid> 


For most cases, there’s really no practical difference between Name and x:Name. As the "x" prefix 
indicates, the x:Name attribute is intrinsic to XAML itself, and you can use it to identify any object 
in the XAML file. The Name attribute is more restrictive: Name is defined by FrameworkElement, so 
you can use it only with classes that derive from FrameworkElement. For a class not derived from 
FrameworkElement, you’ll need to use x:Name instead. Some programmers prefer to be consistent by 
using x:Nome throughout. I tend to use Nome whenever I can and x:Nome otherwise. (However, when 
naming a custom control that is defined in the application assembly, sometimes Nome doesn’t work 
and x:Nome is required.) 

Whether you use Name or x:Name, the rules for the name you choose are the same as the rules for 
variable names. The name can’t contain spaces or begin with a number, for example. All names within 
a particular XAML file must be unique. 

In the MainPage.xaml.es file you’ll want two additional using directives: 

Project: HelloCode | File: MainPage.xaml.es (excerpt) 

using Windows.UI; 
using Windows.UI.Text; 

The first is for the Colors class; the second is for a Font Style enumeration. It’s not strictly necessary 
that you insert these using directives manually. If you use the Colors class or FontStyle enumeration, 
Visual Studio will indicate with a red squiggly underline that it can’t resolve the identifier, at which 
point you can right-click it and select Resolve from the shortcut menu. The new using directive will be 
added to the others in correct alphabetical order (as long as the existing using directives are alpha¬ 
betized). When you're all finished with the code file, you can right-click anywhere in the file and select 
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Organize Usings and Remove Unused Usings to clean up the list. (I’ve done that with this 
MainPage.xaml.es file.) 


The constructor of the Main Page class is a handy place to create a TextBlock, assign properties, and 
then add it to the Grid: 

Project: HelloCode I File: MainPage.xaml.es (excerpt) 

public MainPage() 

{ 

this .InitializeComponentC); 

TextBlock txtblk = new TextBlockO ; 

txtblk.Text = "Hello, Windows 8!" ; 

txtblk.FontFami1y = new FontFamily ("Times New Roman") ; 

txtblk.FontSize = 96; 

txtblk.FontStyle = FontStyle. Italic; 

txtblk.Foreground = new SolidColorBrush(Colors. Yellow); 
txtbl k. Hon. zontal Alignment = Hori zontalAl ignment .Center; 
txtblk.VerticalAlignment = VerticalAlignment .Center; 

contentGrid.ChiIdren.Add(txtblk); 

} 


Notice that the last line of code here references the Grid named contentGrid in the XAML file just 
as if it were a normal object, perhaps stored as a field. (As you’ll see, it actually is a normal object and 
it is a field!) Although not evident in XAML, the Grid has a property named Children that it inherits 
from Panel. This Children property is of type UlElementCollection, which is a collection that imple¬ 
ments the IList<UIEIement> and IEnumemble<UIElement 〉 interfaces. This is why the Grid can support 
multiple child elements. 

Code often tends to be a little wordier than XAML partially because the XAML parser works behind 
the scenes to create additional objects and perform conversions. The code reveals that the FontFomily 
property requires that a FontFamily object be created and that Foreground is of type Brush and 
requires an instance of a Brush derivative, such as SolidColorBrush. Colors is a class that contains 141 
static properties of type Color. You can alternatively create a Color value from ARGB bytes by using 
the static Color.FromArgb method. 

The FontStyle, Horizontal Alignment, and VerticalAlignment properties are all enumeration types, 
where the enumeration is the same name as the property. Indeed, the Text and FontSize properties 
seem odd in that they are primitive types: a string and a double-precision floating-point number. 

You can reduce the code bulk a little by using a style of property initialization introduced in C# 3.0: 


TextBlock txtblk = new TextBlock 

{ 

Text = "Hello, Windows 8!" , 

FontFamily = new FontFamily ("Times New Roman") , 
FontSize = 96, 

FontStyle = FontStyle .Italic, 

Foreground = new SolidColorBrush(Colors .Yel1ow), 
HorizontalAlignment = HorizontalAlignment .Center, 
VerticalAlignment = VerticalAlignment .Center 

}； 
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I’ve tended to use this style a lot in this book. (However, I have not used another popular feature 
introduced in C# 3.0 — implicit typing using the vor keyword — because it tends to obscure rather than 
illuminate the code.) Either way, you can now compile and run the HelloCode project and the result 
should look the same as the XAML version. It looks the same because it basically is the same. 

You can alternatively create the TextBlock and add it to the Children collection of the Grid in the 
OnNovigotedTo override. Or you can create the TextBlock in the constructor, save it as a field, and add 
it to the Grid in OnNavigatedTo. 

Notice that I put the code after the InitiolizeComponent call in the Main Page constructor. 

You can create the TextBlock prior to InitiolizeComponent, but you must add it to the Grid after 
InitiolizeComponent because the Grid does not exist prior to that call. The InitiolizeComponent 
method basically parses the XAML at run time and instantiates all the XAML objects and puts them all 
together in a tree. InitiolizeComponent is obviously an important method, which is why you might be 
puzzled when you can’t find it in the documentation. 

Here’s the story: When Visual Studio compiles the application, it generates some intermediate 
files. You can find these files with Windows Explorer by navigating to the HelloCode solution, the 
HelloCode project, and then the obj and Debug directories. Among the list of files are MainPage.g.cs 
and MainPage.g.i.cs. The "g" stands for "generated. 〃 Both these files define Main Page classes derived 
from Page with the partial keyword. The composite MoinPoge class thus consists of the 
MainPage.xaml.es file under your control plus these two generated files, which you don’t mess with. 
Although you don't edit these files, they are important to know about because they might pop up in 
Visual Studio if a run-time error occurs involving the XAML file. 

The MainPage.g.i.cs file is the more interesting of the two. Here you’ll find the definition of the 
InitiolizeComponent method, which calls a static method named Application.LoacJComponent to load 
the MainPage.xaml file. Notice also that this partial class definition contains a private field named 
contentGrid, which is the name you’ve assigned to the Grid in the XAML file. The InitiolizeComponent 
method concludes by setting that field to the actual Grid object created by Application.LoodComponent. 

The content Grid field is thus accessible throughout the Main Page class, but the value will be null 
until InitiolizeComponent is called. 

In summary, parsing the XAML is a two-stage process. At compile time the XAML is parsed to 
extract all the element names (among other tasks) and generate the intermediate C# files in the obj 
directory. These generated C# files are compiled along with the C# files under your control. At run 
time the XAML file is parsed again to instantiate all the elements, assemble them in a visual tree, and 
obtain references to them. 

Where is the standard Main method that serves as an entry point to any C# program? That’s in 
App.g.i.cs, one of two files generated by Visual Studio based on App.xaml. 

Let me show you something else that will serve as just a little preview of dependency properties: 

As I mentioned earlier, many properties that we’ve been dealing with — Font Family, Font Size, 
FontStyle, Foreground, Text, Horizontal Align merit, and VerticalAlignment — have corresponding static 
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dependency properties, named FontFomilyProperty, ForitSizeProperty, and so forth. You might amuse 
yourself by changing a normal statement like this: 

txtblk.FontStyle = FontStyle. Italic; 


to an alternative that might look quite peculiar: 

txtblk.SetValue (TextBlock. FontStyleProperty, FontStyle. Italic); 

What you're doing here is calling a method named SetVolue defined by DependencyObject and 
inherited by TextBlock. YouYe calling this method on the TextBlock object but passing to it the 
static FontStyleProperty object of type D ependencyProperty defined by TextBlock and the value you 
want for that property. There is no real difference between these two ways of setting the FontStyle 
property. Within TextBlock, the FontStyle property is very likely defined something like this: 

public FontStyle FontStyle 



SetValue (Text Block. FontStyleProperty, value) ; 


get 


return (FontStyl e)GetValue (TextBlock .FontStyleProperty); 


I say "very likely” because I’m not privy to the Windows Runtime source code, and that source code 
is likely written in C++ rather than C#, but if the FontStyle property is defined like all other properties 
backed by dependency properties, the set and get accessors simply call SetVolue and GetValue with 
the TextBlock.FontStyleProperty dependency property. This is extremely standard code, and it’s a pat¬ 
tern you’ll come to be so familiar with that you’ll generally define your own dependency properties 
without so much white space like this: 

public FontStyle FontStyle 
{ 

set { SetVal ue(TextBl ock. FontStyleProperty, value); } 

get { return (FontStyl e)GetValue (TextBlock. FontStyleProperty); } 

} 

Earlier you saw how you can set the Foreground and font-related properties in XAML on the Page 
tag rather than the TextBlock and how these properties are inherited by the TextBlock. Of course you 
can do the same thing in code: 

public MainPage() 

{ 

this. InitializeComponentC); 

this. FontFamily = new FontFami1y ("Ti mes New Roman") ; 

this .FontSize = 96; 

this .FontStyle = FontStyle. Italic; 

this .Foreground = new SolidColorBrush(Colors .Yel1ow); 
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TextBlock txtblk = new TextBlockO ; 

txtblk.Text = "Hello, Windows 8!"; 

txtblk.Ho n’zontalAlignment = HorizontalATignment .Cente r; 
txtblk.VerticalAlignment = VerticalA1ignment .Center; 

contentGrid.Children.Add(txtblk); 

} 

C# doesn’t require the this prefix to access properties and methods of the class, but when you’re 
editing the files in Visual Studio, typing the this prefix invokes IntelliSense to give you a list of available 
methods, properties, and events. 

Images in Code 


The Hellolmage and HelloLocallmage projects earlier in this chapter used the Image element to 
display bitmaps. In XAML, you set the Source property to a URI indicating the location of a bitmap. 
Judging solely from the XAML file, you might have assumed that this Source property is defined as 
a string or perhaps the Uri type. It’s actually more complex than that: The Source property is of type 
ImogeSource, which encapsulates the actual image that the Image element is responsible for dis¬ 
playing. ImogeSource doesn’t define anything on its own and cannot be instantiated, but several 
important classes descend from ImogeSource, as shown in this partial class hierarchy: 

Object 

DependencyObject 

ImogeSource 

BitmopSource 

Bitmaplmage 

WriteableBitmap 

ImogeSource is defined in the Windows.Ul.Xaml.Medio namespace, but the descendent classes are 
in Windows.Ul.Xoml.Media.Imaging. A BitmapSource can't be instantiated either, but it defines public 
PixelWidth and Pixel Height properties as well as a SetSource method that lets you read in bitmap 
data from a file or network stream. Bitmaplmage inherits these members and also defines a UriSource 
property. 

You can use Bitmaplmage for displaying a bitmap from code. Besides defining this UriSource 
property, Bitmaplmage also defines a constructor that accepts a Uri object. In the HellolmageCode 
project, the Grid has been given a name of "contentGrid" and a using directive for Windows.UI.XomI. 
Media.Imaging has been added to the code-behind file. Here’s the Mo in Page constructor: 


Project: HellolmageCode | File: MainPage.xaml.es (excerpt) 

public MainPageO 
{ 

this. InitializeComponentO; 


Uri uri = new Uri ("http ://www.char!espetzold.com/pw6/PetzoldJersey. jpg") ; 
Bitmaplmage bitmap = new Bi tmaplmage(uri ); 
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Image image = new Image (); 
image.Source = bitmap; 
contentGrid.Chi Idren.Add(image); 


Setting a Name of "contentGrid” on the Grid is not strictly necessary for accessing the Grid from 
code. The Grid is actually set to the Content property of the Page, so rather than accessing the Grid 
like so: 


contentGrid.Children.Add(image); 


you can do it like this: 

Grid grid = this .Content as Grid; 
grid.Chi Idren.Add(image); 

In fact, the Grid isn’t even necessary in such a simple program. You can effectively remove the Grid 
from the visual tree by setting the Image directly to the Content property of Main Page: 

this. Content = image; 

The Content property that MainPage inherits from UserControl is of type UlElement, so it can support 
only one child. Generally, the child of the Main Page is a Panel derivative that supports multiple 
children, but if you need only one child, you can use the Content property of the MainPage directly. 

It’s also possible to make a hybrid of the XAML and code approaches: to instantiate the Image 
element in XAML and create the Bitmoplmoge in code, or to instantiate both the Image element and 
Bitmoplmoge in XAML and then set the UriSource property of Bitmoplmoge from code. I’ve used the 
first approach in the HelloLocallmageCode project, which has an Images directory with the Greeting, 
png file. The XAML file already contains the Image element, but it doesn’t reference an actual bitmap: 


Project: HelloLocallmageCode I File: MainPage.xaml (excerpt) 

<Crid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Image Name="image" 

Stretch="None" /> 

</Grid> 


The code-behind file sets the Source property of the Image element in a single line: 


Project: HelloLocallmageCode I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 
{ 

public MainPageC) 

{ 

this .InitializeComponent(); 

image.Source = new Bi tmaplmage(new Uri ("ms-appx:///Images/Greeting.png ")) ； 
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Look at that special URL for referencing the content bitmap file from code. In XAML, that special 
prefix is optional. 


Are there general rules to determine when to use XAML and when to use code? Not really. I tend 
to use XAML whenever possible except when the repetition becomes ridiculous. My normal rule 
for code is "three or more: use a for," but I’ll often allow somewhat more repetition in XAML before 
moving it into code. A lot depends on how concise and elegant you’ve managed to make the XAML 
and how much effort it would be to change something. 


Not Even a Page 


Insights into how a Windows Runtime program starts up can be obtained by examining the 
OnLounched override in the standard App.xaml.es file. You’ll discover that it creates a Frame object, 
uses this Frame object to navigate to an instance of MoinPage (which is how Main Page gets 
instantiated), and then sets this Frame object to a precreated Window object accessible through the 
Window.Current static property. Here’s the simplified code: 

var rootFrame = new Frame() ; 

rootFrame■Navi gate (typeof (MainPage)) ; 

Window. Current.Content = rootFrame; 

Window. Current.Activate(); 

A Windows 8 application doesn’t require a Page derivative, a Frame, or even any XAML files at 
all. Let’s conclude this chapter by creating a new project named StrippedDownHello and begin by 
deleting the App.xaml, App.xaml.es, MainPage.xaml, and MainPage.xaml.es files, as well as the entire 
Common folder. Yes, delete them all! Now the project has no code files and no XAML files. It’s left 
with just an app manifest, assembly information, and some PNG files. 


Right-click the project name and select Add and New Item. Select either a new class or code file 
and name it App.cs. Here’s what you’ll want it to look like: 

Project: StrippedDownHello | File: App.cs 

using Windows.ApplicationModel.Activation; 

using Windows.UI; 

using Windows.UI.Xaml; 

using Windows.UI.Xaml.Controls; 

using Windows.UI.Xaml.Media; 


namespace StrippedDownHello 
{ 

public cl ass App : Application 
{ 

static void Mai n(stri ng [] args) 
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{ 


Application. Start((p) => new AppO); 



protected override void OnLaunched(LaunchActi vatedEventArgs args) 

{ 

TextBlock txtblk = new TextBlock 

{ 

Text = "Stripped-Down Windows 8", 

FontFamily = new FontFami1y ("Lucida sans Typewriter") , 
FontSize = 96 ， 

Foreground = new SolidColorBrush (Colors. Red), 

Horizontal Alignment = Hon. zontal Alignment .Center, 

VerticalAlignment = Vertical Alignment .Center 

}； 


Window. Current.Content = txtblk; 
Window .Current.Activate(); 



That’s all you need (and obviously much less if you want default properties on the TextBlock). 

The static Main method is the entry point and that creates a new App object and starts it going, and 
the OnLounched override creates a TextBlock and makes it the content of the application’s default 
window. 

I won’t be pursuing this approach to creating Windows 8 applications in this book, but obviously 
it works. 
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CHAPTER 2 


XAML Syntax 


A Windows 8 application is divided into code and markup because each has its own strength. 

Despite the limitations of markup in performing complex logic or computational tasks, it’s good 
to get as much of a program into markup as possible. Markup is easier to edit with tools and shows 
a clearer sense of the visual layout of a page. Of course, everything in markup is a string, so markup 
sometimes becomes cumbersome in representing complex objects. Because markup doesn’t have the 
loop processing common in programming languages, it can also be prone to repetition. 

These issues have been addressed in the syntax of XAML in several ways, the most important of 
which are explored in this chapter. But let me begin this vital subject with a topic that will at first 
appear to be completely off topic: defining a gradient brush. 


The Gradient Brush in Code 


The Background property in Grid and the Foreground property of the Text Block are both of 
type Brush. The programs shown so far have set these properties to a derivative of Brush called 
SolidColorBrush. As demonstrated in Chapter 1, "Markup and Code,” you can create a SolidColorBrush 
in code and give it a Color value; in XAML this is done for you behind the scenes. 

SolidColorBrush is only one of four available brushes, as shown in this class hierarchy: 

Object 

DependencyObject 

Brush 

SolidColorBrush 

GrodientBrush 

LinearGrodientBrush 

TileBrush 

ImageBrush 

WebViewBrush 

Only SolidColorBrush, LineorGradientBrush, ImageBrush, and WebViewBrush are instantiable. Like 
many other graphics-related classes, most of these brush classes are defined in the Windows.Ul.Xaml 
.Medio namespace, although WebViewBrush is defined in Windows.Ul.Xaml.Controls. 
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The LinearGrodientBrush creates a gradient between two or more colors. For example, suppose 
you want to display some text with blue at the left gradually turning to red at the right. While we’re at 
it, let's set a similar gradient on the Background property of the Grid but going the other way. 

In the GradientBrushCode program, a Text Block is instantiated in XAML, and both the Grid and the 
TextBlock have names: 

Project: GradientBrushCode I File: MainPage.xaml (excerpt) 

<Grid Name="contentGri d" 

Background=” {StaticResource ApplicationPageBackgroundThemeBrush}"> 

<TextBlock Name="txtbl k" 

Text="Hello, Windows 8!" 

FontSi ze="96" 

FontWei ght="Bold" 

HorizontalAli gnment="Center" 

VerticalA1i gnment="Center" /> 

</Grid> 


The constructor of the code-behind file creates two separate LineorGrodientBrush objects to set to 
the Background property of the Grid and Foreground property of the TextBlock: 

Project: GradientBrushCode I File: MainPage.xaml.es (excerpt) 

public MainPage() 

{ 

this. InitializeComponentC); 


// Create the foreground brush for the TextBlock 

LinearGradientBrush foregroundBrush = new LinearGradi entBrush() ; 

foregroundBrush.StartPoint = new Poi nt(0, 0); 
foregroundBrush.EndPoint = new Poi nt(l, 0); 

GradientStop gradientStop = new Gradi entStopO ; 

gradientStop.Offset = 0; 

gradientStop.Col or = Colors. Blue; 

foregroundBrush.GradientStops.Add(gradientStop); 

gradi entStop = new Gradi entStopO ; 
gradientStop.Offset = 1; 
gradientStop.Col or = Colors .Red; 
foregroundBrush.GradientStops.Add(gradientStop); 

txtblk.Foreground = foregroundBrush; 


// Create the background brush for the Grid 
LinearGradientBrush backgroundBrush = new LinearGradientBrush 
{ 

StartPoint = new Poi nt(0, 0 )， 

EndPoint = new Point(l, 0) 

}； 

backgroundBrush.GradientStops.Add (new GradientStop 

{ 

Offset = 0, 

Color = Colors .Red 

}); 
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backgroundBrush.GrachentStops. Add(new GradientStop 
{ 

Offset = 1 ， 

Color = Colors. Blue 

}); 

contentGrid.Background = backgroundBrush; 


The two brushes are created with two different styles of property initialization, but otherwise 
they’re basically the same. The LinearGradientBrush class defines two properties named Start Point and 
EndPoint of type Point, which is a structure with X and Y properties representing a two-dimensional 
coordinate point. The Start Point and EndPoint properties are relative to the object to which the brush 
is applied based on the standard windowing coordinate system: X values increase to the right and Y 
values increase going down. The relative point (0, 0) is the upper-left corner and (1, 0) is the upper- 
right corner, so the brush gradient extends along an imaginary line between these two points, and 
all lines parallel to that line. The StortPoint and EndPoint defaults are (0, 0) and (1, 1), which defines a 
gradient from the upper-left to the lower-right corners of the target object. 

LinearGradientBrush also has a property named GrodientStops that is a collection of GrocJientStop 
objects. Each GrodientStop indicates an Offset relative to the gradient line and a Color at that offset. 
Generally the offsets range from 0 to 1, but for special purposes they can go beyond the range 
encompassed by the brush. LinearGradientBrush defines additional properties to indicate how the 
gradient is calculated and what happens beyond the smallest Offset and the largest Offset. 

Here’s the result: 



If you now consider defining these same brushes in XAML, all of a sudden the limitations of 
markup become all too evident. XAML lets you define a SolidColorBrush by just specifying the color, 
but how on earth do you set a Foreground or Background property to a text string defining two 
points and two or more offsets and colors? 
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Property-Element Syntax 


Fortunately, there is a way. As you’ve seen, you normally indicate that you want a SolidColorBrush in 
XAML simply by specifying the color of the brush: 

<TextBlock Text="Hel1 o, Windows 8!" 

Foreground="Bl ue" 

FontSize="96" /> 

The SolidColorBrush \s created for you behind the scenes. 

However, it’s possible to use a variation of this syntax that gives you the option of being more 
explicit about the nature of this brush. Remove that Foreground property, and separate the TextBlock 
element into start and end tags: 

〈TextBlock Text="Hello, Windows 8!" 

FontSi ze="96"> 


〈 /TextBlock 〉 

Within those tags, insert additional start and end tags consisting of the element name, a period, 
and a property name: 

〈TextBlock Text="Hello, Windows 8!” 

FontSi ze="96"> 

<TextBlock.Foreground 〉 

< /TextBlock.Foreground 〉 

</TextBlock> 

And within those tags put the object you want to set to that property: 

〈TextBlock Text="Hel 1o, Windows 8!" 

FontSi ze="96"> 

<TextBlock.Foreground 〉 

〈SolidColorBrush Col or="Bl ue" /> 

</TextBlock.Foreground 〉 

</TextBlock> 

Now it’s explicit that Foreground is being set to an instance of a SolidColorBrush. 

This is called property-element syntax, and if s an important feature of XAML. At first it might 
seem to you (as it did to me) that this syntax is an extension or aberration of standard XML, but it’s 
definitely not. Periods are perfectly valid characters in XML element names. 
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In reference to that last little snippet of XAML it is now possible to categorize three types of XAML 
syntax: 

■ The TextBlock and SolidColorBrush are both examples of "object elements” because they are 
XML elements that result in the creation of objects. 

■ The Text, FontSize, and Color settings are examples of "property attributes .〃 They are XML 
attributes that specify the settings of properties. 

■ The TextBlock.Foreground tag is a "property element." It is a property expressed as an XML 
element. 

XAML poses a restriction on property-element tags: Nothing else can go in the start tag. The 
object being set to the property must be content that goes between the start and end tags. 

The following example uses a second set of property-element tags for the Color property of the 
SolidColorBrush: 

〈TextBlock Text="Hello, Windows 8!" 

FontSize="96"> 

<TextBlock.Foreground 〉 

<SolidColorBrush> 

<SolidColorBrush.Color> 

B1 ue 

</SolidColorBrush.Color> 

〈 /SolidColo 「 Brush 〉 

</TextBlock.Foreground 〉 

〈 /TextBlock 〉 


If you want, you can set the other two properties of the TextBlock similarly: 


<TextBlock> 

<TextBlock.Text> 

Hello, Windows 8 
〈 /TextBlock.Text 〉 

<TextBlock.FontSi ze> 

96 

</TextBlock.FontSize> 

cTextBlock.Foreground 〉 

<SolidColorBrush> 

<SolidColorBrush.Color> 
B1 ue 

</SolidColorBrush.Color> 
</SolidColorBrush> 
</TextBlock.Foreground 〉 
〈 /TextBlock 〉 
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But there’s really no point. For these simple properties, the property attribute syntax is shorter and 
clearer. Where property-element syntax comes to the rescue is in expressing more complex objects 
like LineorGradientBrush. Let’s begin again with the property-element tags: 

〈TextBlock Text="Hel lo, Windows 8!" 

FontSize="96"> 

<TextBlock.Foreground 〉 

</TextBlock.Foreground 〉 

</TextBlock> 


Put a LineorGradientBrush in there, separated into start tags and end tags. Set the Start Point and 
End Point properties in this start tag: 

〈TextBlock Text="Hello, Windows 8!" 

FontSize="96 M > 

<TextBlock.Foreground 〉 

<LinearGradientBrush StartPoi nt="0 0" EndPoi nt="l 0"> 

</LinearGradientBrush> 

</TextBlock.Foreground 〉 

〈 /TextBlock 〉 


Notice that the two properties of type Point are specified with two numbers separated by a space. 
You can separate the number pair with a comma if you choose. 

The LinearGrodientBrush has a Gradient Stops property that is a collection of GrodientStop objects, 
so include the Gradient Stops property with another property element: 

<TextBlock Text="Hello, Windows 8!" 

FontSize="96"> 

<TextBlock.Foreground 〉 

<LinearGradientBrush StartPoi nt="0 0" EndPoi nt="l 0"> 

<LinearGradientBrush.GradientStops> 

</LinearGradientBrush.GradientStops> 

</LinearGradientBrush> 

</TextBlock.Foreground 〉 

</TextBlock> 


The GradientStops property is of type GradientStopCollection, so let’s add that in as well: 

〈TextBlock Text="Hello, Windows 8!" 

FontSi ze="96"> 

<TextBlock.Foreground 〉 

<LinearGradientBrush StartPoi nt="0 0" EndPoi nt="l 0"> 

<LinearGradientBrush.GradientStops> 

<GradientStopCol1ecti on> 

</GradientStopCol1ection> 

</LinearGradientBrush.GradientStops> 

</LinearGradientBrush> 

</TextBlock.Foreground 〉 

</TextBlock> 
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Finally, add the two GradientStop objects to the collection: 

〈TextBlock Text="Hello, Windows 8!" 

FontSi ze="96"> 

<TextBlock.Foreground 〉 

<LinearGradientBrush StartPoi nt="0 0" EndPoi nt="l 0"> 
<LinearGradientBrush.GradientStops> 

<GradientStopCol1ection> 

<GradientStop 0ffset="0" Color="Bl ue" /> 
〈GradientStop 0ffset="l" Color="Red" /> 
</GradientStopCol1ection> 

</LinearGradientBrush.GradientStops> 

</LinearGradientBrush> 

</TextBlock.Foreground 〉 

</TextBlock> 


And there we have it: a rather complex property setting expressed entirely in markup. 

Content Properties 

The syntax I’ve just shown you for instantiating and initializing the LineorGrodientBrush is actually a 
bit more extravagant than what you actually need. You might be persuaded of this fact when you 
consider that all the XAML files we’ve seen so far have apparently been missing some properties and 
elements. Look at this little snippet of markup: 

<Page … > 

<Grid … > 

<TextBlock … /> 

<TextBlock … /> 

<TextBlock … /> 

</Gri d> 

</Page> 


We know from working with the classes in code that the Text Block elements are added to the Children 
collection of the Grid, and the Grid is set to the Content property of the Page. But where are those 
Children and Content properties in the markup? 

Well, you can include them if you want. Here are the Poge.Content and Grid-Children property 
elements as they are allowed to appear in a XAML file: 

<Page … > 

<Page.Content> 

<Gri d ... > 

<Grid.Children> 

<TextB1ock … /> 

<TextBlock … /> 

<TextBlock … /> 

</Grid.Children> 

</Grid> 

</Page.Content> 

</Page> 


CHAPTER 2 XAML Syntax 


37 




This markup is still missing the UlElementCollection object that is set to the Children property of the 
Grid. That cannot be explicitly included because only elements with parameterless public constructors 
can be instantiated in XAML files, and the UlElementCollection class is missing such a constructor. 

The real question is this: Why aren’t the Poge.Content and Grid.Children property elements 
required in the XAML file? 

Simple: All classes referenced in XAML are allowed to have one (and only one) property that is 
designated as a "content” property. For this content property, and only this property, property- 
element tags are not required. 


The content property for a particular class is specified as a .NET attribute. Somewhere in the actual 
class definition of the Panel class (from which Grid derives) is an attribute named ContentProperty. If 
these classes were defined in C#, it would look like this: 

[ContentProperty(Name="Chi Idren")] 
public class Panel : FrameworkElement 
{ 

} 

What this means is simple. Whenever the XAML parser encounters some markup like this: 

<Gri d ... > 

<TextBlock ... /> 

<TextBlock … /> 

<TextBlock … /> 

</Grid> 


then it checks the ContentProperty attribute of the Grid and discovers that these Text Block elements 
should be added to the Children property. 

Similarly, the definition of the User Control class (from which Page derives) defines the Content 
property as its content property (which might sound appropriately redundant if you say it out loud): 

[ContentProperty(Name="Content")] 
public class UserControl : Control 
{ 

} 


You can define a ContentProperty attribute in your own classes. The ContentPropertyAttribute class 
required for this is in the Windows.Ul.Xoml.Markup namespace. 

Unfortunately, at the time I’m writing this book, the documentation for the Windows Runtime 
indicates only when a ContentProperty attribute has been set on a class — look in the Attributes 
section of the home page for the Panel class, for example — but not what that property actually is! 
Perhaps the documentation will be enhanced in the future, but until then, you’ll just have to learn by 
example and retain by habit. 
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Fortunately, many content properties are defined to be the most convenient property of the class. 
For LinearGradientBrush, the content property is GradientStops. Although GrocJientStops is of type 
GrocJientStopCollection, XAML does not require collection objects to be explicitly included. Here’s the 
excessively wordy form of the LinearGradientBrush syntax: 

〈TextBlock Text="Hello, Windows 8!" 

FontSi ze="96"> 

<TextBlock.Foreground 〉 

〈LinearGradientBrush StartPoi nt="0 0" EndPoi nt="l 0"> 

<LinearGradientBrush.GradientStops> 

<GradientStopCol1ecti on> 

<GradientStop 0ffset="0" Color="Bl ue" /> 

<GradientStop 0ffset="l" Color="Red" /> 

</GradientStopCol1ecti on> 

</LinearGradientBrush.GradientStops> 

</LinearGradientBrush> 

</TextBlock.Foreground 〉 

</TextBlock> 

Neither the LineorGrodientBrush.GradientStops property elements nor the GrodientStopCollection tags 
are required, so it simplifies to this: 

〈TextBlock Text="Hello, Windows 8!" 

FontSi ze="96"> 

<TextBlock.Foreground 〉 

<LinearGradientBrush StartPoi nt="0 0" EndPoi nt="l 0"> 

〈GradientStop 0ffset="0" Color="Bl ue" /> 

〈GradientStop 0ffset="l" Color="Red" /> 

</LinearGradientBrush> 

</TextBlock.Foreground 〉 

</TextBlock> 


Now it’s difficult to imagine how it can get any simpler and still be valid XML 

It is now possible to rewrite the GradientBrushCode program so that everything is done in XAML: 


Project: GradientBrushMarkup | File: MainPage.xaml (excerpt) 

<Grid> 

<Grid.Background 〉 

<LinearGradientBrush StartPoi nt="0 0" EndPoi nt="l 0"> 
<GradientStop 0ffset="0" Color="Red" /> 

〈GradientStop 0ffset="l" Color="Blue" /> 

</LinearGradientBrush> 

</Grid.Background 〉 

<TextBlock Name="txtbl k" 

Text="Hel lo, Windows 8!" 

FontSi ze="96" 

FontWei ght="Bold" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Center"> 

<TextBlock.Foreground> 

<LinearGradientBrush StartPoi nt="0 0" EndPoi nt="l 0"> 
〈GradientStop 0ffset="0" Color="Blue" /> 
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<GradientStop Offset="l" Color="Red" /> 
</LinearGradientBrush> 

</TextBlock.Foreground> 

</TextBlock> 

</Grid> 


Even with the property-element syntax, it’s more readable than the code version. What code 
illustrates most clearly is how something is built. Markup shows the completed construction. 

Here's something to watch out for. Suppose you define a property element on a Grid with multiple 
children: 

<Gri d> 

<Grid.Background 〉 

<SolidColorBrush Color="Blue" /> 

</Grid.Background 〉 

<TextBlock Text="one" /> 

〈TextBlock Text="two" /> 

〈TextBlock Text="three" /> 

</Grid> 


You can alternatively put the property element at the bottom: 

<Gri d> 

<TextBlock Text="one" /> 

<TextBlock Text="two" /> 

〈TextBlock Text="three" /> 


<Grid.Background 〉 

<SolidColorBrush Color="Blue" /> 
</Grid.Background 〉 

</Grid> 


But you can’t have some content before the property element and some content after it: 

<!-- This doesn't work!--> 

<Gri d> 

<TextBlock Text="one" /> 


<Grid.Background 〉 

<SolidColorBrush Color="Blue" /> 
</Grid.Background 〉 

〈TextBlock Text="two" /> 

〈TextBlock Text="three" /> 

</Crid> 


Why the prohibition? The problem becomes very apparent when you include the property-element 
tags for the Children property: 

<!-- This doesn't work!--> 

<Gri d> 

<Grid.Chi 1dren> 

<TextBlock Text="one" /> 

</Grid.Children> 


PART: Elementals 


<Grid.Background 〉 

<SolidColorBrush Col or="Bl ue" /> 
</Grid.Background 〉 


<Grid.Children> 

<TextBlock Text="two" /> 
<TextBlock Text="three" /> 
</Grid.Children> 

</Grid> 


Now it’s obvious that the Children property is defined twice with two separate collections, and that’s 
not legal. 

The TextBlock Content Property 

As you saw in the WrappedText program in Chapter 1, TextBlock allows you to specify text as content. 
However, the content property of TextBlock is not the Text property. It is instead a property named 
Inlines of type InlineCollection, a collection of Inline objects, or more precisely, instances of Inline 
derivatives. The Inline class and its derivatives can all be found in the Windows.Ul.Xaml.Documents 
namespace. Here’s the hierarchy: 

Object 

DependencyObject 

TextElement 

Block 

Paragraph 

Inline 

InlineUIContainer 

LineBreak 

Run (defines Text property) 

Span (defines Inlines property) 

Bold 

Italic 

Underline 

These classes allow you to specify varieties of formatted text in a single TextBlock. TextElement 
defines Foreground and all the font-related properties: FontFamily, FontSize, FontStyle, FontWeight (for 
setting bold), Font St retch (expanded and compressed for fonts that support it), and ChorocterSpocing, 
and these are inherited by all the descendent classes. 

The Block and Paragraph classes are mostly used in connection with a souped-up version of 
TextBlock called RichTextBlock that I’ll discuss in Chapter 16, "Rich Text" The remainder of this 
discussion will focus entirely on classes that derive from Inline. 

The Run element is the only class here that defines a Text property, and Text is also the content 
property of Run. Any text content in an InlineCollection is converted to a Run, except when that text is 
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already content of a Run. You can also use Run objects explicitly to specify different font properties of 
the text strings. 

Span defines an Inlines property just like TextBlock. This allows Span and its descendent classes 
to be nested. The three descendent classes of Span are shortcuts. For example, the Bold class is 
equivalent to Span with the FontWeight attribute set to Bold. 

As an example, here's a TextBlock with a small Inlines collection using the shortcut classes with 
nesting: 


〈 TextBlock 〉 

Text in <Bol d>bol d</Bold> and <Itali c>i tali c</Italic> and 
<Boldxltali obold itali c</Italicx/Bold> 

</TextBlock> 


As this is parsed, all those pieces of loose text are converted to Run objects, so the Inlines collection of 
the TextBlock contains six items: instances of Run, Bold, Run, Italic, Run, and Bold. The Inlines collection 
of the first Bold item contains a single Run object as does the Inlines collection of the first Italic 
item. The Inlines collection of the second Bold item contains an Italic object, whose Inlines collection 
contains a Run object. 

The use of Bold and Italic with a TextBlock demonstrates clearly how the syntax of XAML is based 
on the classes and properties that support these elements. It wouldn’t be possible to nest an Italic tag 
in a Bold tag if Bold didn’t have an Inlines collection. 

Here’s a somewhat more extensive TextBlock that shows off more formatting features: 


Project: TextFormatting | File: MainPage.xaml (excerpt) 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
〈TextBlock Wi dth="400" 

FontSi ze="24" 

TextWrappi ng="Wrap" 

HornzontalAli gnment="Center" 

VerticalAli gnment="Center"> 

Here is text in a 

<Run FontFami ly="Times New Roman ">Times New Roman</Run> font, 
as well as text in a 

<Run FontSi ze="36">36-pixel</Run> height. 

<LineBreak /> 

<LineBreak /> 

Here is some <Bold>bold</Bold> and here is some 
<Itali c>"i tali c</Itali c> and here is some 
<Underli ne>underl i ne</Underline> and here is some 
<BoldxltalicxUnderli ne>bol d italic underline and 
<Span FontSize=" 36 ">bigger and 
<Span Foreground="Red">Red</Span> as wel 1</Span> 

</Underl i nex/Ital i cx/Bold>. 

</TextBlock> 

</Grid> 
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The TextBlock is given an explicit 400-pixel width so that it doesn’t sprawl too wide. Individual 
Run elements can always be used to format pieces of text as shown in the first several lines in this 
paragraph, but if you want nested formatting — and particularly in connection with the shortcut 
classes — youll want to switch to Span and its derivatives: 


Here is text in a Times New Roman 

font, as well as text in a 36-piXGl 
height. 

Here is some bold and here is some 
italic and here is some underline and 
here is some bold italic underline 

and bigger and Red as 
well 


As you can see, the LineBreak element can arbitrarily break lines. In theory, the InlineUIContoiner 
class allows you to embed any UlElement in the text (for example, Image elements), but it only works 
with RichTextBlock and not the regular TextBlock. 


Sharing Brushes (and Other Resources) 


Suppose you have multiple TextBlock elements on a page, and you want several of them to have 
the same brush. If this is a SolidColorBrush, the repetitive markup is not too bad. However, if ifs a 
LineorGradientBrush, it gets messier. A LinearGradientBrush requires at least six tags, and all that 
repetitive markup becomes very painful, particularly if something needs to be changed. 

The Windows Runtime has a feature called the "XAML resource" that lets you share objects among 
multiple elements. Sharing brushes is one common application of the XAML resource, but the most 
common is defining and sharing styles. 

XAML resources are stored in a ResourceDictionory, a dictionary whose keys and values are both of 
type object. Very often, however, the keys are strings. Both FromeworkElement and Application define 
a property named Resources of type ResourceDictionory. 
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The SharedBrush project shows a typical way to share a LinearGrodientBrush (and a couple other 
objects) among several elements on a page. Toward the top of the XAML file I’ve defined a Resources 
property element for the collection of resources for that page: 


Project: SharedBrush I File: MainPage.xaml (excerpt) 

<Page … > 


<Page.Resources 〉 

<x: String x: Key="appName">Shared Brush App</x: String> 


<LinearGradientBrush x : Key=" rainbowBrush"> 

<GradientStop 0ffset="0" Color="Red" /> 

<GradientStop 0ffset="0. 17" Color="Orange" /> 
<GradientStop 0ffset="0 .33" Color="Yel low" /> 
<GradientStop 0ffset="0 .5" Color="Green" /> 
<GradientStop 0ffset="0 .67" Color="Blue" /> 
<GradientStop 0ffset="0 .83" Color="Indigo" /> 
<GradientStop Offset="l" Color="Viol et" /> 
</LinearGradientBrush> 


<FontFamily x:Key="fontFami ly">Times New Roman</FontFami 1y> 

<x: Double x: Key="fontSi ze">96</x: Double> 

</Page.Resources 〉 

</Page> 

Often the definition of resources near the top of a XAML file is referred to as a "resources section.” 
This particular Resources dictionary is initialized with four items of four different types: String, 
LinearGrodientBrush, Font Family, and Double. Notice the "x" prefix on String and Double. These are 
•NET primitive types, of course, but they are not Windows Runtime types, and hence they are not in 
the default XAML namespace. Also available are x:Boolean and x:lnt32 types. 

Notice as well that each of these objects has an x:Key attribute. The x:Key attribute is valid only 
in a Resources dictionary. As the name suggests, the x:Key attribute is the key for that item in the 
dictionary. 

In the body of the XAML file, an element references the resource by using this key in some special 
markup called a XAML markup extension. 

There are just a few XAML markup extensions, and you’ll always recognize them by curly braces. 
The markup extension for referencing a resource consists of the keyword StoticResource and the key 
name. In fact, you’ve already seen the StoticResource markup extension numerous times: It provides 
the standard Grid with a background brush. The rest of this XAML file uses StoticResource to obtain 
items defined in the Resources dictionary: 


Project: SharedBrush I File: MainPage.xaml (excerpt) 

<Page … > 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<TextBlock Text="{StaticResource appName}" 

FontSi ze="48" 
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HorizontalA1i gnment="Center" 
VerticalAli gnment="Center" /> 


〈TextBlock Text="Top Text" 

Foreground="{Stati cResource rainbowBrush} 
FontFami ly="{StaticResource fontFamily}" 
FontSi ze="{StaticResource fontSi ze}" 
HorizontalAl ignment="Center" 

VerticalA1i gnment="Top" /> 

<TextBlock Text="Left Text" 

Foreground="{Stati cResource rainbowBrush} 
FontFami ly="{StaticResource fontFamily}" 
FontSi ze="{StaticResource fontSi ze}" 

HorizontalA1i gnment="Left" 

VerticalAli gnment="Center" /> 


〈TextBlock Text="Ri ght Text" 

Foreground="{Stati cResource rainbowBrush} 
FontFami ly="{StaticResource fontFamily}" 
FontSi ze="{StaticResource fontSi ze}" 

HorizontalA1i gnment="Ri ght" 

VerticalAli gnment="Center" /> 

<TextBlock Text="Bottom Text" 

Foreground="{Stati cResource rainbowBrush} 
FontFami ly="{StaticResource fontFamily}" 
FontSi ze="{StaticResource fontSi ze}" 

HorizontalA1i gnment="Center" 

VerticalAli gnment="Bottom" /> 

</Gri d> 

</Page> 

Here’s the result: 


Top .t 


Left 、t Shared Brush App ligh 


Bottom 1 Kt 
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A few notes: 


Referencing the same three resources in four Text Block elements cries out for a more efficient 
approach, namely, a style, which I’ll discuss later in this chapter. 

Resources must be defined in a XAML file lexically preceding their use. This is why it's most 
common for the Resources dictionary to be near the top of a XAML file and most conveniently 
defined on the root element. 


However, every FrameworkElement descendent can support a Resources dictionary, so you might 
include them further down the visual tree. The keys must be unique within any Resources dictionary, 
but you can use duplicate keys in other Resources dictionaries. When the XAML parser encounters 
a StaticResource markup extension, it begins searching up the visual tree for a Resources dictionary 
with a matching key and it uses the first one it encounters. You can effectively override the values of 
Resources keys with those in more local dictionaries. 

If the XAML parser cannot find a matching key by searching up the visual tree, it checks the 
Resources dictionary in the Application object. The App.xaml file is an ideal place for defining 
resources that are used throughout the application. To use a bunch of resources across multiple 
applications, you can define them in a separate XAML file with a root element of ResourceDictionary. 
Include that file in a project, reference it in the App.xaml file, and you can then use items in that 
dictionary. 


Indeed, an example is already provided for you in the standard Visual Studio projects for Windows 
8 applications. The Common folder contains a file named StandardStyles.xaml that has a root element 
of ResourceDictionary: 

<ResourceDictionary 

xml ns="http: //schemas.microsoft.com/winfx/2006/xaml/presentati on" 
xml ns : x="http: //schemas.microsoft.com/winfx/2006/xaml"> 


</ResourceDictionary> 

This file is referenced in the standard App.xaml file. In fact, referencing this resources collection is just 
about all that the standard App.xaml file does: 

<Application 

x:Class="SharedBrush .App" 

xml ns="http: //schemas.microsoft.com/winfx/2006/xaml/presentati on" 
xml ns : x="http: //schemas.microsoft.com/winfx/2006/xaml" 
xml ns : local = n using:SharedBrush"> 

<Application.Resources> 

<ResourceDicti onary> 

<ResourceDictionary.MergedDictionaries> 

<ResourceDictionary Source="Common/StandardStyl es.xaml"/> 

</ResourceDictionary.MergedDictionaries> 

</ResourceDictionary> 

</Application.Resources 〉 

</Applicati on> 
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You can include your own collections of resources by inserting additional ResourceDictionory tags in 
the MergedDictionaries collection. Or you can include your own resources directly in the App object’s 
Resources dictionary. 

You can also reference the Resources dictionary from code. Following the InitiolizeComponent call, 
you can retrieve an item from the dictionary with an indexer: 

FontFami 1 y fntfam = this .Resources ["fontFamily"] as FontFami 1 y ; 

Now try this: Comment out the "fontFamily" entry in the MainPage.xaml file, but add that item to 
the dictionary in the Mo in Page constructor prior to the In i ti olizeComp orient call. 

this .Resources.Add("fontFamily", new FontFamily ("Times New Roman")) ; 

When the XAML file is parsed by InitiolizeComponent, this object will be available within that XAML 
file. 

The ResourceDictionory class does not define a public method that searches up the visual tree 
for dictionaries in ancestor classes. If you need something like that to search for resources in code, 
you can easily write it yourself by "climbing the visual tree" using the Parent property defined by 
FromeworkElement or the VisuolTreeHelper class defined in the Windows.ilI.Xaml.Medio namespace. 
The Application object for the application is available from the static Application-Current property. 

The predefined resources (such as the ApplicotionPageBackgroundThemeBrush referenced by the 
Grid) don't seem to be documented, but you can get a list of their values (in the Default, Light, and 
High Contrast themes) in the file: 

C:\Progrom Files (x86)\Windows Kits\8.0\lnclude\winrt\xoml\design\themeresources.xaml 


After ApplicationPageBockgroundThemeBrush, the next most important predefined resource 
identifier is ApplicationForegroundThemeBrush, which is black in the light theme, and white in the 
dark theme. If you need a color to properly contrast with the background (as I will shortly), this is 
it. For a convenient highlight color that contrasts with both background and foreground, create 
a SolidColorBrush based on the Highlight color available from the UlElementColor method of the 
UlSettings class. 


Resources Are Shared 


Are resource objects truly shared among the elements that reference them? Or are separate instances 
created for each StoticResource reference? 

Try inserting the following code after the InitiolizeComponent call in the SharedBrush.xaml.es file: 


TextBlock txtblk = (this .Content as Grid) .Children[1] as TextBlock; 

LinearGradientBrush brush = txtblk.Foreground as LinearGradientBrush ; 
brush.StartPoint = new Poi nt(0 , 1); 
brush.EndPoint = new Poi nt(0, 0); 
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This code references the LinearGradientBrush of the second Text Block in the Children collection of the 
Grid and changes the Start Point and EndPoint properties. Lo and behold, all the TextBlock elements 
referencing that LinearGradientBrush are affected: 




Left Text shared Brush a pp Right Text 


iSi>i it hii i GXl 


Conclusion: Resources are shared. 

It’s also easy to verify that even if a resource is not referenced by any element, it is still instantiated. 

Exploring Vector Graphics 

As you’ve seen, displaying text and bitmaps in a Windows 8 application involves creating objects of 
type TextBlock and Image and attaching them to a visual tree. There’s no concept of "drawing” or 
"painting," at least not on the application level. Internal to the Windows Runtime, the TextBlock and 
Image elements are rendering themselves. 


Similarly, if you wish to display some vector graphics — lines, curves, and filled areas — you 
don’t do it by calling methods like Draw Line and Draw Bezier. These methods do not exist in the 
Windows Runtime! Methods with names like those exist in DirectX, which you can use in a Windows 
8 application, but when using the Windows Runtime you instead create elements of type Line, 
Polyline, Polygon, and Path. These classes derive from the Shape class (which itself derives from 
FrameworkElement) and can all be found in the Windows.ilI.Xaml.Shopes namespace, which is 
sometimes referred to as the Shapes library. 

The most powerful members of the Shapes library are Polyline and Path. Polyline renders a 
collection of connected straight lines, but its real purpose is to draw complex curves. All you need 
to do is keep the individual lines short and supply plenty of them. Don’t hesitate to give Polyline 
thousands of lines. That’s what it’s there for. 
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Let’s use Polyline to draw an Archimedean spiral. The XAML file for the Spiral program instantiates 
the Polyline object but doesn’t include the points that define the figure: 

Project: Spiral | File: MainPage.xaml (excerpt) 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

〈Polyline Name="polyl ine" 

Stroke="{Stati cResource ApplicationForegroundThemeBrush}" 

StrokeThickness="3" 

HorizontalAli gnment="Center" 

VerticalA1i gnment="Center" /> 

</Grid> 

The Stroke property (inherited from Shape) is the brush used to draw the actual lines. Generally, this 
is a SolidColorBrush, but you’ll see shortly that it doesn’t have to be. I’ve used StaticResource with the 
predefined identifier that provides a white brush with a dark theme and a black brush with a light 
theme. StrokeThickness (also inherited from Shape) is the width of the lines in pixels, and you've seen 
Horizon to I A lignmen t and VerticalAlignment before. 


It might seem a little strange to specify Horizon to I A lignment and VerticalAlignment for a chunk of 
vector graphics, so a little explanation might be in order. 

Two-dimensional vector graphics involve the use of coordinate points in the form [X, Y) on a 
Cartesian coordinate system, where X is a position on the horizontal axis and / is a position on the 
vertical axis. Vector graphics in the Windows Runtime use a coordinate convention commonly associ¬ 
ated with windowing environments: Values of X increase to the right (as is normal), but values of Y 
increase going down (which is opposite the mathematical convention). 

When only positive values of X and Y are used, the origin — the point (0, 0) — is the upper-left 
corner of the graphical figure. 

Negative coordinates can be used to indicate points to the left of the origin or above the origin. 
However, when the Windows Runtime calculates the dimensions of a vector graphics object for layout 
purposes, these negative coordinates are ignored. For example, suppose you draw a polyline with 
points that have X coordinates ranging from -100 to 300 and Y coordinates ranging from -200 to 
400. This implies that the polyline has a dimension of 400 pixels wide and 600 pixels high, and that is 
certainly true. But for purposes of layout and alignment, the polyline is treated as if it were 300 pixels 
wide and 400 pixels tall. 

For a vector graphics figure to be treated in a predictable manner in the Windows Runtime layout 
system, all that’s required is that you regard the point (0, 0) as the upper-left corner. For purposes of 
layout, the maximum positive X coordinate becomes the element’s width and the maximum positive Y 
coordinate becomes the element’s height. 


For specifying a coordinate point, the Windows.Foundation namespace includes a Point structure 
that has two properties of type double named X and Y. In addition, the Windows.Ul.Xoml.Medio 
namespace includes a PointCollection, which is a collection of Point objects. 

The only property that Polyline defines on its own is Points of type PointCollection. A collection 
of points can be assigned to the Points property in XAML, but for very many points calculated 
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algorithmically, code is ideal. In the constructor of the Spiral class, a for loop goes from 0 to 3600 
degrees, effectively spinning around a circle 10 times: 


Project: Spiral | File: MainPage.xaml.es (excerpt) 

public MainPageO 
{ 

this .InitializeComponentC); 

for (int angle =0; angle < 3600; angle++) 

{ 

double radians = Math .PI * angle / 180; 
double radius = angle / 10; 
double x = 360 + radius * Math■ Sin(radians); 
double y = 360 + radius * Math. Cos(radians); 
polyline.Points.Add (new Poi nt(x, y)); 



The radians variable converts degrees to radians for the .NET trig functions, and radius is calculated 
to range from 0 through 360 depending on the angle, which means that the maximum radius will be 
360 pixels. The values returned by the Math.Sin and Math.Cos static methods are multiplied by radius, 
which means these products will range between -360 and 360 pixels. 


To shift this figure so that all pixels have positive values relative to an upper-left origin, 360 is 
added to both products. The spiral is thus centered at the point (360, 360) and extends no more than 
360 pixels in all directions. 

The loop concludes by instantiating a Point value and adding it to the Points collection of the 
Polyline. Here it is: 
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Without the Horizontal Alignment and VerticolAlignment settings, the figure would be aligned at 
the upper-left corner of the page. If the adjustment for the spiral’s center is also removed from the 
calculation, the center would be in the upper-left corner of the page and three-quarters of the figure 
would not be visible. If you keep HorizontalAlignmerit and VerticolAlignment set to Center but remove 
the adjustment for the spiral’s center, you’ll see the figure positioned so that the lower-right quadrant 
is centered. 

The spiral almost fills the screen, but that’s only because the screen I’m using for these images has 
a height of 768 pixels. What if we wanted to ensure that the spiral filled the screen regardless of the 
screen’s size? 

One solution is to base the numbers going into the calculation of the spiral coordinates directly on 
the pixel size of the screen. You’ll see how to do that in Chapter 3, "Basic Event Handling.” 

Another solution requires noticing that the Shape class defines a property named Stretch that you 
use in exactly the same way you use the Stretch property of Image. By default, the Stretch property 
for Polyline is the enumeration member Stretch.None, which means no stretching, but you can set it to 
Uniform so that the figure fills the container while maintaining its aspect ratio. 

The StretchedSpiral project demonstrates this. The XAML file sets a larger stroke width as well: 

Project: StretchedSpiral I File: MainPage.xaml (excerpt) 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

〈Polyline Name="polyl ine" 

Stroke="{StaticResource ApplicationForegroundThemeBrush}" 

StrokeThi ckness="6" 

Stretch="Uni form" /> 

</Grid> 

The code-behind file calculates the coordinates of the spiral using arbitrary coordinates, which in 
this case I’ve chosen based on a radius of 1000: 


Project: StretchedSpiral I File: MainPage.xaml.es (excerpt) 

public MainPageO 
{ 

this. InitializeComponentO; 

for (int angle =0; angle < 3600; angle++) 

{ 

double radians = Math .PI * angle / 180; 
double radius = angle / 3.6; 
double x = 1000 + radius * Math .Sin(radians); 
double y = 1000 - radius * Math .Cos(radians); 
polyline.Points.Add (new Poi nt(x, y)); 
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You might also notice that I changed a plus to a minus in they calculation so that the spiral ends at 
the top rather than the bottom. The switch to the light theme demonstrates the convenience of using 
ApplicationForegroundThemeBrush for the Stroke color: 



Try setting the Stretch property to Fill to see this circular spiral be distorted into an elliptical spiral. 

You’ll recall how LinearGradientBrush adapts itself to the size of whatever element it’s applied to. 
The same is true when using that brush with vector graphics. Let’s instead try an ImageBrush, which is 
a brush created from a bitmap. 

The code-behind file for ImageBrushedSpiral is the same as StretchedSpiral. The XAML file widens 
the stroke considerably and instantiates an ImogeBrush: 


Project: ImageBrushedSpiral | File: MainPage.xaml (excerpt) 

<Crid Background:'' {StaticResource ApplicationPageBackgroundThemeBrush}"> 

〈Polyline Name="polyli ne" 

StrokeThi ckness="25" 

Stretch="Uni form"> 

<Polyline.Stroke> 

<ImageBrush ImageSource="http: //www.charlespetzold.com/pw6/PetzoldJersey.jpg" 
Stretch="Uni formToFi11" 

A1 ignmentY="Top" /> 

</Polyline.Stroke> 

</Polyline> 

</Grid> 


The ImageSource property of ImogeBrush is of type ImogeSource, just like the Source property of 
Image. In XAML you can just set it to a URL. ImogeBrush has its own Stretch property, which by default 
is Fill. This means that the bitmap is stretched to fill the area without respecting the aspect ratio. For 
the image I’m using, that would make me look fat, so I switched to UniformToFill, which maintains the 
image’s aspect ratio while filling the area. Doing so requires part of the image to be cropped. Use 
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the AlignmentX and AlignmentY properties to indicate how the bitmap should be aligned with the 
graphical figure, and consequently, where the image should be cropped. For this bitmap, I prefer that 
the bottom be cropped rather than my head: 



Notice that the alignment of the image seems to be based on the geometric line of the spiral 
rather than the line rendered with a width of 25 pixels. This causes areas at the top, left, and right 
sides to be shaved off. The problem can be fixed with the Transform property of ImogeBrush, but 
that’s a little too advanced for this chapter. 

You may have noticed that ImageBrush derives from Tile Brush. That heritage might suggest that 
you could repeat bitmap images horizontally and vertically to tile a surface, but doing so is not 
supported by the Windows Runtime. 

Any curve that you can define with parametric formulas, you can render with Polyline. But if the 
complex curves you need are arcs (that is, curves on the circumference of an ellipse), cubic Bezier 
splines (the standard sort), or quadratic Bezier splines (which have only one control point), you don’t 
need to use Polyline. These curves are all supported with the Path element. 

Path defines just one property on its own called Data, of type Geometry, a class defined in 
Windows.Ul.Xaml.Media. In the Windows Runtime, Geometry and related classes represent pure 
analytic geometry. The Geometry object defines lines and curves using coordinate points, and the 
Path renders those lines with a particular stroke brush and thickness. 

The most powerful and flexible Geometry derivative is PothGeometry. The content property of 
PothGeometry is named Figures, which is a collection of PothFigure objects. Each Path Figure is a 
series of connected straight lines and curves. The content property of PothFigure is Segments, a 
collection of PathSegment objects. PothSegment is the parent class to LineSegment, PolylineSegment, 
BezierSegment, PolyBezierSegment, QuodroticBezierSegment, PolyQuodroticBezierSegment, and 
ArcSegment. 
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Let’s display the word HELLO using Path and PathGeometry: 


Project: HelloVectorGraphics I File: MainPage.xaml (excerpt) 

<Crid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Path Stroke="Red" 

StrokeThi ckness="12" 

StrokeLine]oi n="Round" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Center"> 

<Path.Data> 

<PathGeometry> 

<! —— H --> 

<PathFigure StartPoi nt="0 0"> 

<LineSegment Poi nt="0 100" /> 

</PathFigure> 

<PathFigure StartPoi nt="0 50"> 

<LineSegment Poi nt="50 50" /> 

</PathFigure> 

<PathFigure StartPoi nt="50 0"> 

<LineSegment Poi nt="50 100" /> 

</PathFigure> 


<!-- E --> 

<PathFigure StartPoi nt="125 0"> 

<BezierSegment Pointl="60 -10" Point2="60 60" Point3="125 50" /> 
<BezierSegment Poi ntl="60 40" Poi nt2="60 110" Poi nt3="125 100" /> 
</PathFigure> 


<PathFigure StartPoi nt="150 0"> 

<LineSegment Poi nt="150 100" /> 
<LineSegment Poi nt="200 100" /> 
</PathFigure> 


<PathFigure StartPoi nt="225 0"> 

<LineSegment Poi nt="225 100" /> 
<LineSegment Poi nt="275 100" /> 
</PathFigure> 


<!-- 0 --> 

<PathFigure StartPoi nt="300 50"> 

<ArcSegment Si ze="25 50" Poi nt="300 49.9" IsLargeArc="True" /> 

</PathFigure> 

</PathGeometry> 

〈 /Path.Data 〉 

</Path> 

</Grid> 

Each letter is one or more Path Figure objects, which always specifies a starting point for a series of 
connected lines. The PothSegment derivatives continue the figure from that point. For example, to 
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draw the 〃 E ,〃 BezierSegment specifies two control points and an end point. The next BezierSegment 
then continues from the end of the previous segment. (In the ArcSegment, the end point for the arc 
can’t be the same as the start point or nothing will be drawn. That why it’s set to l/10 th pixel short. A 
better alternative is to split the ArcSegment into two, each drawing half the circle.) 

The result suggests that a pair of Bezier splines was perhaps not the best way to render a capital E: 



Try setting the Stretch property of Path to Fill for a "really big hello": 



Of course you can assemble the Path Figure and PathSegment objects in code, but let me 
show you an easier way to do it in XAML. A Path Markup Syntax is available that consists of single 


CHAPTER 2 XAML Syntax 


55 




letters, coordinate points, an occasional size, and a couple Boolean values that reduce the markup 
considerably. The HelloVectorGraphicsPath project creates the same figure as HelloVectorGraphics: 


Project: HelloVectorGraphicsPath I File: MainPage.xaml (excerpt) 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

<Path Stroke="Red" 

StrokeThi ckness="12" 

StrokeLineJoi n="Round" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Center" 

Data="M 0 0 L 0 100 M 0 50 L 50 50 M 50 0 L 50 100 

M 125 0 C 60 -10, 60 60, 125 50, 60 40, 60 110, 125 100 

M 150 0 L 150 100, 200 100 

M 225 0 L 225 100, 275 100 

M 300 50 A 25 50 0 1 0 300 49.9" /> 

</Grid> 

The Data property is now one big string, but IVe separated it into five lines corresponding to the five 
letters. The M code is a "move" followed byx and y coordinate points. This indicates the start of a 
figure. The L is a line (or, more precisely, a polyline) followed by one or more points; C is a cubic Bezier 
curve, followed by control points and an end point, but more than one can be included; and A is an 
arc. The arc is by far the most complex: The first two numbers indicate the horizontal and vertical radii 
of an ellipse, which is rotated a number of degrees given by the next argument. Following are two 
flags for the Is Large Arc property and sweep direction, followed by the end point. Not used here is the 
often useful Z, which closes a figure with a straight line back to the start point. 

Defining a complex geometry in terms of Path Markup Syntax is one example of something that 
can be done only in XAML. Whatever class performs this conversion is not publicly exposed in the 
Windows Runtime. It is available only to the XAML parser. To convert a string of Path Markup Syntax 
to a Geometry in code would require some way to convert XAML to an object in code. 

Fortunately, something like that is available. It’s a static method named XomlReoder.Lood in the 
Windows.Ul.Xoml.Markup namespace. Pass it a string of XAML and get out an instance of the root 
element with all the other parts of the tree instantiated and assembled. XomIReader.Load has some 
restrictions — the XAML it parses can’t refer to event handlers in external code, for example — but it is 
a very powerful facility. In Chapter 8, "App Bars and Popups,” I’ll show you the source code for a tool 
called XamICruncher that lets you interactively experiment with XAML. 

Meanwhile, here’s a Path with Path Markup Syntax created entirely in code: 


Project: PathMarkupSyntaxCode | File: MainPage.xaml.es 


using Windows.UI; 
using Windows.UI.Xaml; 
using Windows.UI.Xaml.Controls; 
using Windows.UI.Xaml .Markup; 
using Windows.UI.Xaml.Media; 
using Windows.UI.Xaml.Shapes; 


// for Colors 

// for XamlReader 
// for Path 
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namespace PathMarkupSyntaxCode 

{ 

public sealed partial cl ass MainPage : Page 

{ 

public MainPageO 

{ 

this. InitializeComponent(); 

Path path = new Path 

{ 

Stroke = new SolidColorBrush (Colors. Red), 

StrokeThickness = 12 ， 

StrokeLineJoin = PenLineJoin .Round, 

HorizontalAlignment = HorizontalAlignment .Center, 

VerticalAlignment = VerticalAlignment .Center, 

Data = PathMarkupToGeometryC 

"M 0 0 L 0 100 M 0 50 L 50 50 M 50 0 L 50 100 " + 

"M 125 0 C 60 -10 ， 60 60 ， 125 50 ， 60 40 ， 60 110 ， 125 100 " + 

"M 150 0 L 150 100 ， 200 100 " + 

"M 225 0 L 225 100 ， 275 100 " + 

"M 300 50 A 25 50 0 1 0 300 49.9") 


(this .Content as Grid) .Children.Add(path); 

} 

Geometry PathMarkupToGeometryCstri ng pathMarkup) 

{ 

string xaml = 

"<Path " + 

"xmlns='http://schemas.microsoft.com/winfx/2006/xaml/presentation'>" + 
"<Path. Data>" + pathMarkup + "</Path. Datax/Path>" ; 

Path path = XamlReader. Load(xaml) as Path ; 

// Detach the PathGeometry from the Path 
Geometry geometry = path.Data; 
path.Data = null; 
return geometry; 



Watch out when working with the Path class in code: The MainPage.xaml.es file that Visual Studio 
generates does not include a using directive for Windows.Ul.Xoml.Shapes where Path resides but does 
include a using directive for System. 10, which has a very different Path class for working with files and 
directories. 

The magic method is down at the bottom. It assembles a tiny piece of legal XAML with Path as 
the root element and property-element syntax to enclose the string of Path Markup Syntax. Notice 
that the XAML must include the standard XML namespace declaration. \f Xaml Reader. Load doesn’t 
encounter any errors, it returns a Path with a Doto property set to a PathGeometry. However, you 
can’t use this PathGeometry for another Path unless you disconnect it from this Path, which requires 
setting the Data property of the returned Path to null. 
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Stretching with Viewbox 


Both the Image class and the Shape class define a Stretch property that can stretch the 
bitmap or vector graphics to the size of its container. This property is not universal among the 
FrameworkElement derivatives. After all, why would you ever want to stretch a TextBlock in such a 
way? 

Well, sometimes you need to do precisely that. Suppose you were displaying a bunch of 
objects with text titles. You want these items to look similar with each title restricted to a particular 
rectangular area. But the length of the text might be variable. Perhaps the user types in this text. If 
the text is very long, you might prefer that it be shrunk down a bit to fit the rectangle. While you 
could always perform a Font Size calculation in the code-behind file, it would be nice to have the 
TextBlock sized automatically to fit a particular space. 

This a job for Viewbox, which has a Child property of type UlElement and which stretches that 
child to its own size. Like Image and Shape, Viewbox defines a Stretch property. The default setting 
is Uniform (the same default as Image), but the following program sets Stretch to Fill to ignore the 
aspect ratio of a TextBlock and make it fill the screen: 

Project: TextStretch | File: MainPage.xaml (excerpt) 

<Grid Background=" {StaticResource ApplicationPageBackgroundThemeBrush}"> 

<Viewbox Stretch="Fil1 "> 

〈TextBlock Text="Stretch Windows 8!" /> 

</Viewbox> 

</Crid> 

TextBlock always calculates its height to encompass diacritics and descenders even if they don’t 
exist in the text, which is why the text doesn't quite extend to the full height of the window: 
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Still, it definitely no longer has the correct aspect ratio. 

Unlike Image and Shape, Viewbox defines a StretchDirection property that can take on values of 
UpOnly, Down Only, or Both (the default). This instructs Viewbox to only increase the size of its child or 
only decrease the size if that’s what you want. 

Suppose you wanted to modify the HelloVectorGraphics program so that each letter is a different 
color. Instead of using one Path element you’d need to split it up into five Path elements. But if you 
then try to use the Stretch property of Path to stretch each letter to the size of the window, it wouldn’t 
work because each letter has a different size. 

Instead, put all five Path elements in a Grid, and put the Grid inside a Viewbox: 

Project: VectorGraphicsStretch I File: MainPage.xaml (excerpt) 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
cViewbox Stretch:" Fi11"> 

<Grid Margin="6 6 0 0"> 

<!-- H --> 

<Path Stroke="Red" 

StrokeThi ckness="12" 

StrokeLineJoi n="Round" 

Data="M 0 0 L 0 100 M 0 50 L 50 50 M 50 0 L 50 100" /> 

<!-- E --> 

〈Path Stroke="#C00040" 

StrokeThi ckness="12" 

StrokeLine]oi n="Round" 

Data="M 125 0 C 60 -10, 60 60, 125 50, 60 40, 60 110, 125 100" /> 

<!-- L --> 

〈Path Stroke="#800080" 

StrokeThi ckness="12" 

StrokeLineJoi n="Round" 

Data="M 150 0 L 150 100, 200 100" /> 

<!-- L --> 

〈Path Stroke="#4000C0" 

StrokeThi ckness="12" 

StrokeLineJoi n="Round" 

Data="M 225 0 L 225 100, 275 100" /> 

<!-- 0 --> 

〈Path Stroke="Bl ue" 

StrokeThi ckness="12" 

StrokeLineJoi n="Round" 

Data="M 300 50 A 25 50 0 1 0 300 49.9" /> 

</Grid> 

</Viewbox> 

</Grid> 
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Now the whole ensemble of vector graphics is sized uniformly: 



Notice also that the Viewbox increases the stroke width along with the size of the graphics, 
whereas setting Stretch on the Path element does not. 


Styles 


You’ve seen how brushes can be defined as resources and shared among elements. By far the most 
common use of resources is to define styles, which are instances of the Style class. A style is basically a 
collection of property definitions that can be shared among multiple elements. The use of styles not 
only reduces repetitive markup, but also allows easier global changes. 

After this discussion, much of the StandardStyles.xaml file included in the Common folder of your 
Visual Studio projects will be comprehensible, except for large sections within ControlTemplote tags. 
That’s coming up in Chapter 11, "The Three Templates." 

The SharedBrushWithStyle project is much the same as SharedBrush except that it uses a Style to 
consolidate several properties. Here’s the new Resources section with the Style near the bottom: 


Project: SharedBrushWithStyle | File: MainPage.xaml (excerpt) 

<Page.Resources 〉 

<x: String x : Key="appName">Shared Brush with Styl e</x : String> 


<Li nearGradientBrush x : Key="rai nbowBrush"> 

<GradientStop 0ffset="0" Color="Red" /> 

<GradientStop 0ffset="0 .17" Color="Orange" /> 
<GradientStop 0ffset="0 .33" Color="Yel low" /> 


<GradientStop 0ffset="0 .5" Color="Green" /> 
<GradientStop 0ffset="0 .67" Color="Bl ue" /> 
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<GradientStop 0ffset="0 .83" Color="Indigo" /> 
<GradientStop Offset="l" Color="Violet" /> 
</LinearGradientBrush> 


〈Style x : Key=" rainbowStyle" TargetType="TextBlock"> 

〈Setter Property="FontFami ly" Value="Times New Roman" /> 

〈Setter Property="FontSi ze" Value="96" /> 

〈Setter Property=" Foreground" Val ue="{StaticResource rainbowBrush}" /> 
</Style> 

</Page.Resources 〉 


Like all resources, the start tag of the Style includes an x:Key attribute. Style also requires 
a Targe tType attribute indicating either FromeworkElement ora class that derives from 
FromeworkElement. Styles can be applied only to FromeworkElement derivatives. 

The body of the Style includes a bunch of Setter tags, each of which specifies Property and Value 
attributes. Notice that the last one has its Value attribute set to a StaticResource of the previously 
defined LinearGrodientBrush. For this reference to work, this particular Style must be defined later in 
the XAML file than the brush, although it can be in a different Resources section deeper in the visual 
tree. 


Like other resources, an element references a Style by using the StaticResource markup extension 
on its Style property: 


Project: SharedBrushWithStyle | File: MainPage.xaml (excerpt) 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<TextBlock Text="{StaticResource appName}" 

FontSize="48" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Center" /> 

<TextB1ock Text="Top Text" 

Styl e="{StaticResource rainbowStyl e}" 

HorizontalAli gnment="Center" 

VerticalA1i gnment="Top" /> 


〈TextBlock Text="Left Text" 

Styl e="{StaticResource rainbowStyl e} 
HorizontalAli gnment="Left" 

VerticalAli gnment="Center" /> 

<TextBlock Text="Ri ght Text" 

Styl e="{StaticResource rainbowStyle} 
HorizontalAlignment="Ri ght" 

VerticalAli gnment="Center" /> 

<TextBlock Text="Bottom Text" 

Styl e="{StaticResource rainbowStyle} 
HorizontalAli gnment="Center" 

VerticalAli gnment="Bottom" /> 

</Grid> 


Except for the application name, the visuals are the same as the SharedBrush program. 
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There is an alternative way for this particular Style to incorporate the LinearGradientBrush. Just as 
you can use property-element syntax on elements to define an object with complex markup, you can 
use property-element syntax with the Value property of the Setter class: 

<Style x : Key=" rainbowStyle" TargetType="TextBlock"> 

<Setter Property=" FontFami1y" Val ue="Times New Roman" /> 

〈Setter Property="FontSi ze" Value="96" /> 

<Setter Prope rty="Foreg round"> 

<Setter.Value> 

<LinearGradientBrush> 

<GradientStop 0ffset="0" Color="Red" /> 

<GradientStop 0ffset="0 .17" Color="Orange" /> 

<GradientStop 0ffset="0 .33" Color="Yel low" /> 

<GradientStop 0ffset="0 .5" Color="Green" /> 

<GradientStop 0ffset="0 .67" Color="Blue" /> 

<GradientStop 0ffset="0 .83" Col or="Indi go" /> 

<GradientStop Offset="l" Color="Violet" /> 

</LinearGradientBrush> 

</Setter.Value> 

</Setter> 

</Styl e> 

I know it looks a little odd at first, but defining brushes within styles is very common. Notice that the 
LinearGradientBrush now has no x:Key of its own. Only items defined at the root level in a Resources 
collection can have x:Key attributes. 

You can define a Style in code, for example, like so: 

Style style = new Style(typeof (TextBlock)) ; 

style.Setters.Add (new Setter (Text B1ock. FontSizeProperty, 96)); 
style.Setters.Add (new Setter (Text Block. FontFamilyProperty, 

new FontFami lyC'Times New Roman "))) ； 

You could then add this to the Resources collection of a Page prior to the InitializeComponent call so 
that it would be available to TextBlock elements defined in the XAML file. Or you could assign this 
Style object directly to the Style property of a TextBlock. This isn’t common, however, because code 
offers other solutions for defining the same properties on several different elements, namely, the for 
or foreach loop. 

Take careful note of the first argument to the Setter constructor in the code example. It’s defined 
as a Dependency Property, and what you specify is a static property of type DependencyProperty 
defined by (or inherited by) the target class of the style. This is an excellent example of how 
dependency properties allow a property of a class to be specified independently of a particular in¬ 
stance of that class. 
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The code also makes clear that the properties targeted by a Style can only be dependency 
properties. I mentioned earlier that dependency properties impose a hierarchy on the way that 
properties can be set For example, suppose you have the following markup in this program: 

〈TextBlock Text="Top Text" 

Style="{StaticResource rainbowStyl e}" 

FontSi ze="24" 

HorizontalA1i gnment="Center" 

VerticalA1i gnment="Top" /> 

The Style defines a FontSize value, but the FontSize property is also set locally on the Text Block. As 
you might hope and expect, the local setting takes precedence over the Style setting, and both take 
precedence over a FontSize value propagated through the visual tree. 

Once a Style object is set to the Style property of an element, the Style can no longer be changed. 
You can later set a different Style object to the element, and you can change properties of objects 
referenced by the style (such as brushes), but you cannot set or remove Setter objects or change their 
Value properties. 

Styles can inherit property settings from other styles by using a Style property called BasedOn, 
which is usually set to a StaticResource markup extension referencing a previously defined Style 
definition: 

〈Style x : Key="baseTextBl ockStyle" TargetType="TextBl ock"> 

〈Setter Property="FontFami ly" Val ue="Times New Roman" /> 

〈Setter Property="FontSi ze" Value="24" /> 

〈 /Style 〉 


〈Style x : Key="gradi entStyle" TargetType="Text Block" 

BasedOn="{Stati cResource baseTextBlockStyle}"> 

〈Setter Property="FontSi ze" Value="96" /> 

<Setter Prope rty="Foreg round"> 

<Setter.Value> 

<LinearGradientBrush> 

<GradientStop 0ffset="0" Color="Red" /> 

<GradientStop Offset="l" Color="Blue" /> 

</LinearGradientBrush> 

</Setter.Value> 

</Setter> 

〈 /Style 〉 

The Style with the key "gradientStyle" is based on the previous Style with the key "baseTextBlockStyle," 
which means that it inherits the FontFomily setting, overrides the FontSize setting, and defines a new 
Foreground setting. 

Here’s another example: 

<Style x : Key="centeredStyl e" TargetType="FrameworkEl ement"> 

〈Setter Property="Hori zontalA1ignment" Val ue="Center" /> 

〈Setter Property="Verti calA1ignment" Val ue="Center" /> 

</Style> 
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〈Style x : Key=" rainbowStyle" TargetType="Text Block" 
BasedOn="{StaticResource centeredStyl e}"> 

<Setter Property="FontSi ze" Value="96" /> 

<Setter Prope rty="Foreg round"> 

<Setter.Value> 

<LinearGradientBrush> 

<GradientStop 0ffset="0" Color="Red" /> 
<GradientStop Offset="l" Color="Blue" /> 
</LinearGradientBrush> 

</Setter.Value> 

</Setter> 

</Style> 


In this case, the first Style has a TargetType of FrameworkEIement, which means that it can include only 
properties defined by FromeworkElement or inherited by FrameworkElement. You can still use this 
style for a Text Block because TextBlock derives from FromeworkElement. The second Style is based on 
"centeredStyle" but has a TargetType of TextBlock, which means it can also include property settings 
specific to TextBlock. The TargetType must be the same as the Based On type or derived from the 
BasedOn type. 

Despite all IVe said about keys being required for resources, a Style is actually the only exception 
to this rule. A Style without an x:Key is a very special case called an implicit style. The Resources section 
of the ImplicitStyle project has an example: 

Project: ImplicitStyle I File: MainPage.xaml (excerpt) 

<Page.Resources 〉 

<x: String x : Key="appName">Impl icit Style App</x: String> 


<Style TargetType="TextBl ock"> 

〈Setter Property="FontFami ly" Value="Times New Roman" /> 
<Setter Property="FontSi ze" Value="96" /> 

<Setter Property="Foreg round"> 

<Setter.Value> 


<LinearGradientBrush> 


<GradientStop 
<GradientStop 
<GradientStop 
<GradientStop 
<GradientStop 
<GradientStop 
<GradientStop 


0ffset="0" Color="Red" /> 
0ffset="0. 17" Color="Orange" /> 
0ffset="0.33" Color="Yellow" /> 
0ffset="0. 5" Color="Green" /> 
0ffset="0.67" Color="Blue" /> 
0ffset="0. 83" Color="Indi go" /> 
Offset="l" Color= M Violet" /> 


</LinearGradientBrush> 


〈 /Setter.Value> 


</Setter> 


</Style> 

</Page.Resources 〉 


A key is actually created behind the scenes. It’s an object of type RuntimeType (which is not a public 
type) indicating the TextBlock type. 


The implicit style is very powerful. Any TextBlock further down the visual tree that does not have its 
Style property set instead gets the implicit style. If you have a page already full of TextBlock elements 


PART: Elementals 


and you then decide that you want them all to be styled the same way, the implicit style makes it very 
easy. Notice that none of these TextBlock elements have their Style properties set: 


Project: ImplicitStyle | File: MainPage.xaml (excerpt) 

<Grid Background:” {StaticResource ApplicationPageBackgroundThemeBrush}"> 


<TextBlock Text="{StaticResource appName}" 

FontFamily=" Portable User Interface" 

FontSize="48" 

Foreground="{Stati cResource ApplicationForegroundThemeBrush}" 
HorizontalAli gnment="Center" 

VerticalA1i gnment="Center" /> 


〈TextBlock Text="Top Text" 

HorizontalAli gnment="Center" 
VerticalAli gnment="Top" /> 

〈TextBlock Text="Left Text" 

HorizontalAli gnment="Left" 
VerticalA1i gnment="Center" /> 

〈TextBlock Text="Ri ght Text" 

HorizontalAlignment="Ri ght" 
VerticalA1i gnment="Center" /> 


〈TextBlock Text="Bottom Text" 

HorizontalAli gnment="Center" 
VerticalAli gnment="Bottom" /> 

</Grid> 


Although I obviously intended for the implicit style to apply to most of the TextBlock elements on 
the page, I didn’t want it to apply to the first one, which appears in the center. If you want certain 
elements on the page not to have this implicit style, you must give those elements an explicit style, or 
provide local settings that override the properties included in the Style object, or set the Style prop¬ 
erty to null. (I’ll show you how to do that in XAML shortly.) In this example, I’ve effectively overridden 
the implicit style in the first TextBlock by giving it the default FontFomily name, an explicit Font Size, 
and a Foreground based on a predefined resource. 


You cannot derive a style from an implicit style. However, an implicit style can be based on a 
nonimplicit style. Simply provide TargetType and BosedOn attributes and leave out the x:Key. 

The implicit style is very powerful, but remember: With great power comes...and you know the 
rest. In a large application, styles can be defined all over the place and visual trees can extend over 
multiple XAML files. It sometimes happens that a style is implicitly applied to an element, but it’s very 
hard to determine where that style is actually defined! 

At this point, you can begin using (or at least start looking at) the TextBlock styles defined in 
the StandardStyles.xaml file. These are called BasicTextStyle, BaselineTextStyle, HeaderTextStyle, 
SubheaderTextStyle, TitleTextStyle, ItemTextStyle, BodyTextStyle, CaptionTextStyle, 
PageHeaderTextStyle, PageSubheaderTextStyle, and SnappedPageHeaderTextStyle, and obviously 
they are for more extensive text layout than I’ve been doing here. 


CHAPTER 2 XAML Syntax 


65 


A Taste of Data Binding 


Another way to share objects in a XAML file is through data bindings. Basically, a data binding 
establishes a connection between two properties of different objects. As you’ll see in Chapter 6, 
"WinRT and MWM," data bindings find their greatest application in linking visual elements on a page 
with data sources, and they form a crucial part of implementing the popular Model-View-ViewModel 
(MVVM) architectural pattern. In MVVM, the target of the binding is a visual element in the View, and 
the source of the binding is a property in a corresponding View Model. As you’ll see in Chapter 11, 
bindings are crucial in defining templates to display data objects. 

You can also use data bindings to link properties of two elements. Like StaticResource, Binding 
is generally expressed as a markup extension, which means that it appears between a pair of curly 
braces. However, Binding is more elaborate than StoticResource and can alternatively be expressed in 
property-element syntax. 

Here’s the Resources section from the SharedBrushWithBinding project: 


Project: SharedBrushWithBinding I File: MainPage.xaml (excerpt) 

<Page.Resources 〉 

<x: String x : Key="appName">Shared Brush with Binding</x: String> 

〈Style TargetType="TextBlock"> 

〈Setter Property="FontFami ly" Value="Times New Roman" /> 
〈Setter Property="FontSi ze" Value="96" /> 

</Style> 

</Page.Resources 〉 


The implicit style for the TextBlock no longer has a Foreground property. The LineorGracJientBrush is 
defined on the first of the four TextBlock elements that use that brush, and the subsequent TextBlock 
elements reference that same brush through a binding: 


Project: SharedBrushWithBinding I File: MainPage.xaml (excerpt) 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<TextBlock Text="{StaticResource appName}" 

FontFamily=" Portable User Interface" 

FontSize="48" 

HorizontalAli gnment="Center" 

VerticalA1i gnment="Center" /> 


〈TextBlock Name="topTextBl ock" 

Text="Top Text" 

HorizontalAli gnment="Center" 
VerticalAli gnment="Top"> 
<TextBlock.Foreground 〉 

<LinearGradientBrush> 


<CradientStop 
<GradientStop 
<GradientStop 
<GradientStop 
<CradientStop 
<CradientStop 


Offset= M 0" Color="Red" /> 
0ffset="0 .17" Color="Orange" /> 
0ffset="0.33" Color="Yellow" /> 
0ffset="0 .5" Color="Green" /> 
0ffset="0.67" Color="Blue" /> 
0ffset="0 .83" Color="Indigo" /> 
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<GradientStop Offset="l" Color="Violet" /> 

</LinearGradientBrush> 

</TextBlock.Foreground> 

</TextBlock> 

<TextBlock Text="Left Text" 

HorizontalAli gnment="Left" 

VerticalAli gnment="Center" 

Foreground="{Bi nding El ementName=topT extBlock, Path=Fo reground}" /> 

<TextBlock Text="Ri ght Text" 

HorizontalAlignment="Ri ght" 

VerticalAli gnment="Center" 

Foreground="{Bi nding El ementName=topTextBl ock, Path=Fo reground}" /> 

<TextBlock Text="Bottom Text" 

HorizontalAli gnment="Center" 

VerticalAlignment=" Bottom"> 

<TextBlock.Foreground> 

〈Binding El ementName="topTextBl ock" Path=" Foreground" /> 

</TextBlock.Foreground> 

</TextBlock> 

</Grid> 

Data bindings are said to have a source and a target. The target is always the property on which 
the binding is set, and the source is the property the binding references. The TextBlock with the 
name "topTextBlock" is considered the source of these data bindings; the three TextBlock elements 
that share the Foreground property are targets. Two of these targets show the more standard way of 
expressing the Binding object as a XAML markup extension: 

Foreground="{Bi ndi ng El ementName=topTextBl ock, Path=Fo reground}" 

XAML markup extensions always appear in curly braces. In the markup extension for Binding, a 
couple properties and values usually need to be set. These properties are separated by commas. The 
ElementNome property indicates the name of the element on which the desired property has been 
set; the Path provides the name of the property. 

When I’m typing a Binding markup extension, I always want to put quotation marks around the 
property values, but that’s wrong. Quotation marks do not appear in a binding expression. 

The final TextBlock shows the Binding expressed in less common property-element syntax: 

<TextBlock.Foreground 〉 

〈Binding El ementName="topTextBl ock" Path=" Foreground" /> 

</TextBlock.Foreground> 

With this syntax, the quotation marks around the element name and path are required. 

You can also create a Binding object in code and set it on a target property by using the Set Binding 
method defined by FrameworkElement. When doing this, you’ll discover that the binding target must 
be a dependency property. 
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The Path property of the Binding class is called Path because it can actually be several property 
names separated by periods. For example, replace one of the Text settings in this project with the 
following: 

Text="{Binding El ementName=topTextBl ock , Path=FontFami ly.Source}" 

The first part of the Path indicates that we want something from the FontFamity property. That 
property is set to an object of type FontFamily, which has a property named Source indicating the 
font family name. The text displayed by this Text Block is therefore "Times New Roman." (This does not 
work in a C++ program. Compound and indexed binding paths are not currently supported.) 

Try this on any TextBlock in this project: 

Text="{Binding RelativeSou rce={RelativeSource Self} , Path=FontSi ze}" 

That’s a RelotiveSource markup extension inside a Binding markup extension, and you use it to 
reference a property of the same element on which the binding is set. 


With StoticResource, Binding, and RelotiveSource, youVe now seen 60 percent of the XAML markup 
extensions supported by the Windows Runtime. The TemplateBinding markup extension won’t turn up 
until Chapter 11. 

The remaining markup extension is not used very often, but when you need it, it’s indispensable. 
Suppose youVe defined an implicit style for the Grid that includes a Background property, and it does 
exactly what you want except for one Grid where you want the Background property to be its default 
value of null. How do you specify null in markup? Like so: 

Background="{x: Nul 1 }" 

Or suppose youVe defined an implicit style and there’s one element where you don’t want any 
part of the style to apply. Inhibit the implicit style like so: 

Style="{x:Null}" 

You have now seen nearly all the elements and attributes that appear with an "x 〃 prefix in 
Windows Runtime XAML files. These are the data types x:Booleon, x:Double, x:lnt32 t x:String, as well 
as the x:Qass, x:Name, and x:Key attributes and the x:Null markup extension. The only one I haven’t 
mentioned is x.'L/Zc/, which must be set to application-wide unique strings that reference resources for 
internationalization purposes. 
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CHAPTER 3 

Basic Event Handling 


T he previous chapters have demonstrated how you can instantiate and initialize elements and 
other objects in either XAML or code. The most common procedure is to use XAML to define the 
initial layout and appearance of elements on a page but then to change properties of these elements 
from code as the program is running. 

As you’ve seen, assigning a Name or x:Name to an element in XAML causes a field to be defined 
in the page class that gives the code-behind file easy access to that element. This is one of the two 
major ways that code and XAML interact. The second is through events. An event is a general- 
purpose mechanism that allows one object to communicate something of interest to other objects. 
The event is said to be "fired” or "triggered” or "raised” by the first object and "handled" by the other. 
In the Windows Runtime, one important application of events is to signal the presence of user input 
from touch, the mouse, a pen, or the keyboard. 

Following initialization, a Windows Runtime program generally sits dormant in memory waiting for 
something interesting to happen. Almost everything the program does thereafter is in response to an 
event, so the job of event handling is one that will occupy much of the rest of this book. 


The Tapped Event 

The UlElement class defines all the basic user-input events. These include 

■ eight events beginning with the word Pointer that consolidate input from touch, the mouse, 
and the pen; 

■ five events beginning with the word Manipulation that combine input from multiple fingers; 

■ two Key events for keyboard input; and 

■ higher level events named Tapped, DoubleTopped, RightTopped, and Holding. 

No, the RightTapped event is not generated by a finger on your right hand; it’s mostly used to 
register right-button clicks on the mouse, but you can simulate a right tap with touch by holding 
your finger down for a moment and then lifting, a gesture that also generates Holding events. It’s the 
application’s responsibility to determine how it wants to handle these. 
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An extensive exploration of touch, mouse, and pen events awaits us in Chapter 13, "Touch, Etc.” 

The only other events that UlElement defines are also related to user input: 

■ Got Foe us and Lost Foe us signal when an element is the target of keyboard input; and 

■ Drag Enter, Drag Over, Drag Leave, and Drop relate to drag-and-drop. 

For now, let’s focus on Topped as a simple representative event. An element that derives from 
UlElement fires a Tapped event to indicate that the user has briefly touched the element with a finger, 
or clicked it with the mouse, or dinged it with the pen. To qualify as a Tapped event, the finger (or 
mouse or pen) cannot move very much and must be released in a short period of time. 

All the user-input events have a similar pattern. Expressed in C# syntax, UlElement defines the 
Topped event like so: 

public event TappedEventHandler Tapped; 

The ToppedEventHondler is defined in the Windows.Ul.Xaml.Input namespace. It’s a delegate type that 
defines the signature of the event handler: 

public delegate void TappedEventHandler (object sender, TappedRoutedEventArgs e); 

In the event handler, the first argument indicates the source of the event (which is always an instance 
of a class that derives from UlElement) and the second argument provides properties and methods 
specific to the Topped event. 

The XAML file for the TapTextBlock program defines a TextBlock with a Name attribute as well as a 
handler for the Topped event: 

Project: TapTextBlock | File: MainPage.xaml (excerpt) 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

<TextBlock Name="txtbl k" 

Text="Tap Text!" 

FontSi ze="96" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Center" 

Tapped="txtbl k_Tapped_l" /> 

</Grid> 

As you type TextBlock attributes in XAML, IntelliSense suggests events as well as properties. These 
are distinguished with little icons: a wrench for properties and a lightning bolt for events. (You’ll 
also see a few with pairs of curly braces. These are attached properties that I’ll describe in Chapter 4, 
"Presentation with Panels.") If you allow it, IntelliSense also suggests a name for the event handler, 
and I let it choose this one. Based solely on the XAML syntax, you really can’t tell which attributes are 
properties and which are events. 
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The actual event handler is implemented in the code-behind file. If you allow Visual Studio to 
select a handler name for you, you’ll discover that Visual Studio also creates a skeleton event handler 
in the MainPage.xaml.es file: 


private void txtbl k_Tapped_l(object sender, TappedRoutedEventArgs e) 

{ 

} 

This is the method that is called when the user taps the Text Block. In future projects, I’ll change the 
names of event handlers to make them more to my liking. Ill remove the private keyword (because 
that’s the default), I’ll change the name to eliminate underscores and preface it with the word On (for 
example OnTextBlockTapped), and I’ll change the argument named e to args. You can rename the 
method in the code file and then click a little global-rename icon to rename the method in the XAML 
file as well. 

For this sample program, I decided I want to respond to the tap by setting the TextBlock to a 
random color. In preparation for that job, I defined fields for a Random object and a byte array for the 
red, green, and blue bytes: 


Project: TapTextBlock I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 
{ 

Random rand = new RandomO; 

byte[] rgb = new byte [3]; 

public MainPageO 
{ 

this .Ini ti alizeComponent(); 

} 

private void txtbl k_Tapped_l(object sender, TappedRoutedEventArgs e) 

{ 

rand.NextBytes(rgb); 

Color clr = Color. FromArgb(255, rgb[0], rgb[l], rgb[2]); 
txtblk.Foreground = new SolidColorBrush(cl r); 

} 

} 

I’ve removed the OnNavigatedTo method because it’s not being used here. In the Tapped event 
handler, the Next Bytes method of the Random object obtains three random bytes, and these are used 
to construct a Color value with the static Color.FromArgb method. The handler finishes by setting the 
Foreground property of the TextBlock to a SolidColorBrush based on that Co/or value. 

When you run this program, you can tap the TextBlock with a finger, mouse, or pen and it will 
change to a random color. If you tap on an area of the screen outside the TextBlock, nothing happens. 
If you're using a mouse or pen, you might notice that you don’t need to tap the actual strokes 
that comprise the letters. You can tap between and inside those strokes, and the TextBlock will still 
respond. It’s as if the TextBlock has an invisible background that encompasses the full height of the 
font including diacritical marks and descenders, and that’s precisely the case. 
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If you look inside the MainPage.g.cs file generated by Visual Studio, you’ll see a Connect method 
containing the code that attaches the event handler to the Topped event of the TextBlock. You can 
do this yourself in code. Try eliminating the Tapped handler assigned in the MainPage.xaml file and 
instead attach an event handler in the constructor of the code-behind file: 

public MainPage() 

{ 

this .InitializeComponentC); 
txtblk.Tapped += txtblk_Tapped_l; 

} 

No real difference. 

Several properties of TextBlock need to be set properly for the Topped event to work. The 
IsHitTestVisible and IsTapEnabled properties must both be set to their default values of true. The 
Visibility property must be set to its default value of Visibility.Visible. If set to Visibility.Collapsed, the 
TextBlock will not be visible at all and will not respond to user input. 

The first argument to the txtblk_Tapped_l event handler is the element that sent the event, in this 
case the TextBlock. The second argument provides information about this particular event, including 
the coordinate point at which the tap occurred, and whether the tap came from a finger, mouse, or 
pen. This information will be explored in more detail in Chapter 13. 

Routed Event Handling 

Because the first argument to the Topped event handler is the element that generates the event, you 
don’t need to give the TextBlock a name to access it from within the event handler. You can simply 
cast the sender argument to an object of type TextBlock. This technique is particularly useful for 
sharing an event handler among multiple elements, and I’ve done precisely that in the RoutedEventsO 
project. 

RoutedEventsO is the first of several projects that demonstrate the concept of routed event 
handling, which is an important feature of the Windows Runtime. But this particular program doesn’t 
show any features particular to routed events. Hence the suffix of zero. For this project I created the 
Topped handler first with the proper signature and my preferred name: 

Project: RoutedEventsO | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 
{ 

Random rand = new RandomO; 

byte[] rgb = new byte [3]; 

public MainPage() 

{ 

this .InitializeComponentC )； 

} 

void OnTextBlockTapped (object sender, TappedRoutedEventArgs args) 

{ 

TextBlock txtblk = sender as TextBlock; 
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rand■NextBytes(rgb); 

Color clr = Color. FromArgb(255, rgb[0], rgb[l], rgb[2]); 
txtblk.Foreground = new SolidColorBrush(cl r); 


Notice that the first line of the event handler casts the sender argument to TextBlock. 

Because this event handler already exists in the code-behind file, Visual Studio suggests that 
name when you type the name of the event in the XAML file. This was handy because I added nine 
TextBlock elements to the Grid: 


Project: RoutedEventsO | File: MainPage.xaml (excerpt) 

<Page 

x:Cl ass="RoutedEventsO. MainPage" 

FontSize="48"> 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
〈TextBlock Text="Left / Top" 

HorizontalAli gnment="Left" 

VerticalAli gnment="Top" 

Tapped="OnTextBlockTapped" /> 


〈TextBlock Text="Right / Bottom" 

HorizontalAli gnment="Ri ght" 

VerticalAl ignment="Bottom" 

Tapped="OnTextBlockTapped" /> 

</Gri d> 

</Page> 

I’m sure you don’t need to see them all to get the general idea. Notice that Fontsize is set for the 
Page so that it is inherited by all the TextBlock elements. When you run the program, you can tap the 
individual elements and each one changes its color independently of the others: 


Left / Top 

Center / Top 

Right / Top 

Left / Center 

Center / Center 

Right / Center 

Left / Bottom 

Center / Bottom 

Right / Bottom 
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If you tap anywhere between the elements, nothing happens. 

You might consider it a nuisance to set the same event handler on nine different elements in the 
XAML file. If so, you’ll probably appreciate the following variation to the program. The RoutedEventsl 
program uses routed input handling, a term used to describe how input events such as Tapped are 
fired by the element on which the event occurs but the events are then routed up the visual tree. 
Rather than set a Tapped handler for the individual TextBlock elements, you can instead set it on the 
parent of one of these elements (for example, the Grid). Here’s an excerpt from the XAML file for the 
RoutedEventsl program: 

Project: RoutedEventsl I File: MainPage.xaml (excerpt) 

<Crid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}" 

Tapped="OnGri dTapped"> 

〈TextBlock Text="Left / Top" 

HorizontalAli gnment="Left" 

VerticalA1i gnment="Top" /> 


〈TextBlock Text="Right / Bottom" 

HorizontalAlignment="Ri ght" 

VerticalA1i gnment="Bottom" /> 

</Grid> 

In the process of moving the Topped handler from the individual TextBlock elements to the Grid, IVe 
also renamed it to more accurately describe the source of the event. 

The event handler must also be modified. The previous Topped handler cast the sender argument 
to a TextBlock. It could perform this cast with confidence because the event handler was set only on 
elements of type TextBlock. However, when the event handler is set on the Grid as it is here, the sender 
argument to the event handler will be the Grid. How can we determine which TextBlock was tapped? 

Easy: The Tapped Routed EventArgs class — an instance of which appears as the second argument to 
the event handler — has a property named OriginolSource, and that indicates the source of the event. 

In this example, OriginolSource can be either a TextBlock (if you tap the text) or the Grid (if you tap 
between the text), so the new event handler must perform a check before casting: 

Project: RoutedEventsl | File: MainPage.xaml.es (excerpt) 

void OnGridTapped (object sender, TappedRoutedEventArgs args) 

{ 

if (args.OriginalSource is TextBlock) 

{ 

TextBlock txtblk = args.OriginalSource as TextBlock; 
rand.NextBytes(rgb); 

Color clr = Color. FromArgb(255, rgb[0], rgb[l], rgb[2]); 
txtblk.Foreground = new Soli dColorBrush(cl r); 
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Slightly more efficient is performing the cast first and then checking if the result is non-null. 


ToppedRoutedEventArgs derives from RoutedEventArgs, which defines OriginalSource and no other 
properties. Obviously, the OriginalSource property is a central concept of routed event handling. The 
property allows elements to process events that originate with their children and other descendents 
in the visual tree and to know the source of these events. Routed event handling lets a parent know 
what its children are up to, and OriginalSource identifies the particular child involved. 

Alternatively, you can set the Topped handler on Mo in Page rather than the Grid. But with 
Main Page there’s an easier way. I mentioned earlier that UlElement defines all the user-input events. 
These events are inherited by all derived classes, but the Control class adds its own event interface 
consisting of a whole collection of virtual methods corresponding to these events. For example, for 
the Topped event defined by UlElement, the Control class defines a virtual method named OnTapped. 
These virtual methods always begin with the word On followed by the name of the event, so they 
are sometimes referred to as "On methods." Page derives from Control through UserControl, so these 
methods are inherited by the Page and Mo in Page classes. 

Here’s an excerpt from the XAML file for RoutedEvents2 demonstrating that the XAML file defines 
no event handlers: 


Project: RoutedEvents2 I File: MainPage.xaml (excerpt) 


<Page 

x:Cl ass=" RoutedEvents2■MainPage" 

xml ns="http: //schemas.microsoft.com/winfx/2006/xaml/presentati on" 
xml ns : x="http://schemas.microsoft.com/winfx/2006/xaml" 
xml ns : 1 ocal="usi ng : RoutedEvents2" 

xml ns : d="http: //schemas.microsoft.com/expression/blend/2008" 

xml ns : mc="http : //schemas.openxmlformats.org/markup-compatibi 1 i ty/2006" 

me:Ignorable="d" 

FontSize="48"> 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<TextBlock Text="Left / Top" 

HorizontalAli gnment="Left" 

VerticalA1i gnment="Top" /> 


<TextBlock Text="Right / Bottom" 

HorizontalAli gnment="Ri ght" 
VerticalAli gnment="Bottom" /> 

</Gri d> 

</Page> 
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Instead, the code-behind file has an override of the OnToppecJ method: 

Project: RoutedEvents2 | File: MainPage.xaml.es (excerpt) 

protected override void OnTapped (TappedRoutedEventArgs args) 

{ 

if (args.OriginalSource is TextBlock) 

{ 

TextBlock txtblk = args.OriginalSource as TextBlock; 
rand.NextBytes(rgb); 

Color clr = Color. FromArgb(255, rgb[0], rgb[l], rgb[2]); 
txtblk.Foreground = new SolidColorBrush(cl r); 

} 

base .OnTapped(args); 

} 

When you're typing in Visual Studio and you want to override a virtual method like OnTapped, 
simply type the keyword override and press the space bar, and Visual Studio will provide a list of 
all the virtual methods defined for that class. When you select one, Visual Studio creates a skeleton 
method with a call to the base method. A call to the base method isn’t really required here, but 
including it is a good habit to develop when overriding virtual methods. Depending on the method 
you're overriding, you might want to call the base method first, last, in the middle, or not at all. 

The On methods are basically the same as the event handlers, but they have no sender argument 
because it would be redundant: sender would be the same as this, the instance of the Page that is 
processing the event. 

The next project is RoutedEvents3. I decided to give the Grid a random background color if that’s 
the element being tapped. The XAML file looks the same, but the revised OnTapped method looks 
like this: 

Project: RoutedEvents3 | File: MainPage.xaml.es (excerpt) 

protected override void OnTapped (TappedRoutedEventArgs args) 

{ 

rand.NextBytes(rgb); 

Color clr = Color. FromArgb(255, rgb[0], rgb[l], rgb[2]); 

SolidColorBrush brush = new SolidColorBrush(cl r); 

if (args.OriginalSource is TextBlock) 

(args.OriginalSource as TextBlock). Foreground = brush; 

else if (args.OriginalSource is Grid) 

(args.OriginalSource as Grid) .Background = brush; 

base .OnTapped(args); 

} 

Now when you tap a TextBlock element, it changes color, but when you tap anywhere else on the 
screen, the Grid changes color. 

Now suppose for one reason or another, you decide you want to go back to the original scheme of 
explicitly defining an event handler separately for each TextBlock element to change the text colors, 
but you also want to retain the OnToppecJ override for changing the Grid background color. In the 
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RoutedEvents4 project, the XAML file has the Topped events restored for TextBlock elements and the 
Grid has been given a name: 


Project: RoutedEvents4 | File: MainPage.xaml (excerpt) 

<Grid Name="contentGri d" 

Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

〈TextBlock Text="Left / Top" 

HorizontalAli gnment="Left" 

VerticalAli gnment="Top" 

Tapped="OnTextBlockTapped" /> 


〈TextBlock Text="Right / Bottom" 

HorizontalAlignment="Ri ght" 
VerticalAli gnment="Bottom" 
Tapped="OnTextBlockTapped" /> 

</Grid> 


One advantage is that the methods to set the TextBlock and Grid colors are now separate and 
distinct, so there’s no need for if-else blocks. The Topped handler for the TextBlock elements can cast 
the sender argument with impunity, and the OnTopped override can simply access the Grid by name: 


Project: RoutedEvents4 | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

Random rand = new RandomO; 

byte[] rgb = new byte [3]; 


public MainPageO 

{ 

this .Ini ti alizeComponent(); 

} 

void OnTextBlockTapped (object sender, TappedRoutedEventArgs args) 

{ 

TextBlock txtblk = sender as TextBlock; 

txtbl k. Foreground = GetRandomBrushO ; 

} 


protected override void OnTapped (TappedRoutedEventArgs args) 

{ 

contentGrid.Background = GetRandomBrushO; 
base.OnTapped(args); 

} 


Brush GetRandomBrushO 

{ 

rand■NextBytes(rgb); 

Color clr = Color. FromArgb(255, rgb[0], rgb[l], rgb[2]); 
return new SolidColorBrush(cl r); 
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However, the code might not do exactly what you want. When you tap a TextBlock, not only does 
the TextBlock change color, but the event continues to go up the visual tree where it’s processed by 
the OnTappecJ override, and the Grid changes color as well! If that’s what you want, you’re in luck. 

If not, then I'm sure you’ll be interested to know that the Topped Routed EventArgs has a property 
specifically to prevent this. If the OnTextBlockTapped handler sets the Handled property of the event 
arguments to true, the event is effectively inhibited from further processing higher in the visual tree. 

This is demonstrated in the RoutedEvents5 project, which is the same as RoutedEvents4 except for 
a single statement in the OnTextBlockTapped method: 


Project: RoutedEvents5 I File: MainPage.xaml.es (excerpt) 

void OnTextBlockTapped (object sender, TappedRoutedEventArgs args) 

{ 

TextBlock txtblk = sender as TextBlock; 

txtbl k. Foreground = GetRandomBrushO ; 
args.Handled = true ; 

} 

Overriding the Handled Setting 

You’ve just seen that when an element handles an event such as Topped and concludes its event 
processing by setting the Handled property of the event arguments to true, the routing of the event 
effectively stops. The event isn’t visible to elements higher in the visual tree. 

In some cases, this behavior might be undesirable. Suppose you're working with an element that 
sets the Handled property to true in its event handler, but you still want to see that event higher in 
the visual tree. One solution is to simply change the code, but that option might not be available. 

The element might be implemented in a dynamic-link library, and you might not have access to the 
source code. 

In RoutedEvents6, the XAML file is the same as in RoutedEvents5: Each TextBlock has a handler set 
for its Topped event. The Tapped handler sets the Handled property to true. The class also defines a 
separate OnPogeTopped handler that sets the background color of the Grid: 

Project: RoutedEvents6 | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 
{ 

Random rand = new RandomO; 

byte[] rgb = new byte [3]; 

public MainPage() 

{ 

this .InitializeComponent(); 

this .AddHandler(UIEl ement .TappedEvent, 

new TappedEventHandl er(OnPageTapped), 
true) ; 

} 
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void OnTextBlockTapped (object sender, TappedRoutedEventArgs args) 

{ 

TextBlock txtblk = sender as TextBlock; 

txtbl k. Foreground = GetRandomBrushO ; 
args.Handled = true; 

} 

void OnPageTapped (object sender, TappedRoutedEventArgs args) 

{ 

contentGrid. Background = GetRandomBrushO ; 

} 

Brush GetRandomBrushO 
{ 

rand■NextBytes(rgb); 

Color clr = Color. FromArgb(255, rgb[0], rgb[l], rgb[2]); 
return new SolidColorBrush(cl r); 

} 

} 

But look at the interesting way that the constructor sets a Topped handler for the Page. Normally, it 
would attach the event handler like so: 

this .Tapped += OnPageTapped; 

In that case the OnPageTapped handler would not get a Topped event originating with the TextBlock 
because the TextBlock handler sets Handled to true. Instead, it attaches the handler with a method 
named AddHondler: 

this. AddHandl er(UIElement .TappedEvent, 

new TappedEventHandl er(OnPageTapped), 
true) ; 

AddHandler is defined by UlElement, which also defines the static UlElement TappedEvent property. 
This property is of type Routed Event. 

Just as a property like Fontsize is backed by a static property named FontSizeProperty of 
type DependencyProperty, a routed event such as Topped is backed by a static property named 
TappedEvent of type Routed Event Routed Event defines nothing public on its own; it mainly exists to 
allow an event to be referenced in code without requiring an instance of an element. 

The AddHandler method attaches a handler to that event. The second argument oi AddHandler is 
defined as just an object, so creating a delegate object is required to reference the event handler. And 
here’s the magic: Set the last argument to true if you want this handler to also receive routed events 
that have been flagged as Handled. 

The AddHandler method isn’t used often, but when you need it, it is essential. 
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Input, Alignment, and Backgrounds 


I have just one more, very short program in the RoutedEvents series to make a couple important 
points about input events. 

The XAML file for RoutedEvents7 has just one TextBlock and no event handlers defined: 


Project: RoutedEvents7 | File: MainPage.xaml (excerpt) 

<Page 

FontSi ze="48"> 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

〈TextBlock Text="Hello, Windows 8!" 

Foreground="Red" /> 

</Gri d> 

</Page> 

The absence of Horizontal Alignment and VerticolAlignment settings on the TextBlock cause it to 
appear in the upper-left corner of the Grid. 


Like RoutedEvents3, the code-behind file contains separate processing for an event originating 
from the TextBlock and an event coming from the Grid: 


Project: RoutedEvents7 | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

Random rand = new RandomO; 

byte[] rgb = new byte [3]; 

public MainPage() 

{ 

this .InitializeComponent(); 

} 

protected override void OnTapped(TappedRoutedEventArgs args) 

{ 

rand.NextBytes(rgb); 

Color clr = Color. FromArgb(255, rgb[0], rgb[l], rgb[2]); 

SolidColorBrush brush = new SolidCol orBrush(cl r); 

if (args.OriginalSource is TextBlock) 

(args.OriginalSource as TextBlock). Foreground = brush; 

else if (args.OriginalSource is Gri d) 

(args.OriginalSource as Gri d) .Background = brush; 

base.OnTapped(args); 

} 

} 
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Here it is: 


Hello, Windows 8! 


As you tap the Text Block, it changes to a random color like normal, but when you tap outside the 
TextBlock, the Grid doesn't change color like it did earlier. Instead, the TextBlock changes color! It's as 
if...yes, it’s as if the TextBlock is now occupying the entire page and snagging all the Tapped events for 
itself. 

And that's precisely the case. This TextBlock has default values of Horizon to I AI ign merit and 
Vertical A lignm en t, but those default values are not Left and Top like the visuals might suggest. The 
default values are named Stretch, and that means that the TextBlock is stretched to the size of its 
parent, the Grid. It's hard to tell because the text still has a 48-pixel font, but the TextBlock has a 
transparent background that now fills the entire page. 

In fact, throughout the Windows Runtime, all elements have default Horizontal Alignment and 
VerticolAlignment values of Stretch, and it's an important part of the Windows Runtime layout system. 
More details are coming in Chapter 4. 

Let's put HorizontalAlignment ar\d VerticolAlignment values in this TextBlock: 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

〈TextBlock Text="Hello, Windows 8!" 

HorizontalAli gnment="Left" 

VerticalAli gnment="Top" 

Foreground="Red" /> 

</Grid> 

Now the TextBlock is only occupying a small area in the upper-left corner of the page, and when you 
tap outside the TextBlock, the Grid changes color. 
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Now change Horizontal Alignment to TextAlignment: 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

<TextBlock Text="Hello, Windows 8!" 

TextAli gnment="Left" 

VerticalAli gnment="Top" 

Foreground="Red" /> 

</Grid> 

The program looks the same. The text is still positioned at the upper-left corner. But now when you 
tap to the right of the TextBlock, the TextBlock changes color rather than the Grid. The TextBlock has 
its default Horizontal Alignment property of Stretch, so it is now occupying the entire width of the 
screen, but within the total width that the TextBlock occupies, the text is aligned to the left. 

The lesson: HorizontolAlignment and TextAlignment are not equivalent, although they might seem 
to be if you judge solely from the visuals. 

Now try another experiment by restoring the HorizontolAlignment setting and removing the 
Background property of the Grid: 

<Gri d> 

〈TextBlock Text="Hello, Windows 8!" 

HorizontalAli gnment="Left" 

VerticalAli gnment="Top" 

Foreground="Red" /> 

</Grid> 

With a light theme, the Grid has an off-white background. When the Background property is 
removed, the background of the page changes to black. But you’ll also experience a change in the 
behavior of the program: The TextBlock still changes color when you tap it, but when you tap outside 
the TextBlock, the Grid doesn’t change color at all. 

The default value of the Background property defined by Panel (and inherited by Grid) is null, and 
with a null background, the Grid doesn’t trap touch events. They just fall right through. 

One way to fix this without altering the visual appearance is to give the Grid a Background 
property of Transparent: 

<Grid Background="Transparent"> 

<TextBlock Text="Hello, Windows 8!" 

HorizontalAli gnment="Left" 

VerticalAli gnment="Top" 

Foreground="Red" /> 

</Grid> 

It looks the same as null, but now you’ll get Topped events with an OriginalSource of Grid. 

The lessons here are important: Looks can be deceiving. An element with default settings of 
Ho rizon to I AIignment and VerticalAlignment might look the same as one with settings of Left and Top, 
but it is actually occupying the entire area of its container and might block events from reaching 
underlying elements. A Panel derivative with a default Background property of null might look the 
same as one with a setting of Transparent, but it does not respond to touch events. 
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I can almost guarantee that sometime in the future, one of these two issues will cause a bug in one 
of your programs that will drive you crazy for the good part of a day, and that this will happen even 
after many years of working with the XAML layout system. 

I speak from experience. 


Size and Orientation Changes 

Many, many years ago when Windows was very young, information about Windows programming 
was hard to find. It wasn’t until the December 1986 issue of Microsoft Systems Journal (the predeces¬ 
sor to MSDN Magazine) that the very first magazine article about Windows programming appeared. 
The article described a program called WHATSIZE (all capital letters, of course), which did little more 
than display the current size of the program’s window. But as the size of the window changed, the 
displayed values reflected that change. 

Obviously, the original WHATSIZE program was written for the Windows APIs of that era, so it 
redrew the display in response to a WM_PAINT message. In the original Windows API, this message 
occurred whenever the contents of part of a program’s window became "invalid" and needed redraw¬ 
ing. A program could define its window so that the entire window was invalidated whenever its size 
changed. 

The Windows Runtime has no equivalent of the WM_PAINT message, and indeed, the entire 
graphics paradigm is quite different. Previous versions of Windows implemented a "direct mode” 
graphics system in which applications drew to the actual video memory. Of course, this occurred 
through a software layer (the Graphics Device Interface) and a device driver, but at some point in the 
actual drawing functions, code was writing into video display memory. 

The Windows Runtime is quite different. In its public programming interface, it doesn’t even have 
a concept of drawing or painting. Instead, a Windows 8 application creates elements — that is, objects 
instantiated from classes that derive from FrameworkElement — and adds them to the application’s 
visual tree. These elements are responsible for rendering themselves. When a Windows 8 applica¬ 
tion wants to display text, it doesn’t draw text but instead creates a TextBlock. When the application 
wants to display a bitmap, it creates an Image element. Instead of drawing lines and Bezier splines and 
ellipses, the program creates Polyline and Path elements. 


The Windows Runtime implements a "retained mode" graphics system. Between your application 
and the video display is a composition layer on which all the rendered output is assembled before it 
is presented to the user. Perhaps the most important benefit of retained mode graphics is flicker-free 
animation, as you’ll witness for yourself toward the end of this chapter and in much of the remainder 
of this book. 

Although the graphics system in the Windows Runtime is very different from earlier versions of 
Windows, in another sense a Windows 8 application is similar to its earlier brethren. Once a program 
is loaded into memory and starts running, it spends most of its time generally sitting dormant in 
memory, waiting for something interesting to happen. These notifications take the form of events and 
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callbacks. Often these events signal user input, but there might be other interesting activity as well. 
One such callback is the OnNavigatedTo method. In a simple single-page program, this method is 
called soon after the constructor returns. 

Another event that might be of interest to a Windows 8 application — particularly one that does 
what the old WHATSIZE program did — is named SizeChanged. Here's the XAML file for the Windows 8 
WhatSize program. Notice that the root element defines a handler for the SizeChanged event: 

Project: WhatSize | File: MainPage.xaml (excerpt) 

<Page 

x:Cl ass="WhatSi ze.Mai nPage" 

FontSize="36" 

Si zeChanged="OnPageSi zeChanged"> 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

<TextBlock HorizontalAli gnment="Center" 

VerticalAli gnment="Top"> 

&#x21A4; 〈Run x : Name="wi dthText" /> pixels &#x21A6; 

</TextBlock> 

<TextBlock HorizontalAli gnment="Center" 

VerticalAli gnment="Center" 

TextAli gnment="Center"> 

&#x21A5; 

<LineBreak /> 

<Run x : Name="hei ghtText" /> pixels 
<LineBreak /> 

&#x21A7; 

</TextBlock> 

</Gri d> 

</Page> 

The remainder of the XAML file defines two Text Block elements containing some Run objects 
surrounded by arrow characters. (You’ll see what they look like soon.) It might seem excessive to set 
three properties to Center in the second TextBlock, but they’re all necessary. The first two center the 
TextBlock in the page; setting TextAlignment to Center results in the two arrows being centered rela¬ 
tive to the text. The two Run elements are given x:Name attributes so that the Text properties can be 
set in code. This happens in the SizeChanged event handler: 


Project: WhatSize I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ ^ 
public MainPage() 

{ 

this .InitializeComponent(); 

} 

void OnPageSizeChanged (object sender, SizeChangedEventArgs args) 

{ 

widthText.Text = args.NewSize.Width.ToStringO ; 
heightText.Text = args.NewSize.Height.ToString(); 
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Very conveniently, the event arguments supply the new size in the form of a Size structure, and 
the handler simply converts the Width and Height properties to strings and sets them to the Text 
properties of the two Run elements: 


1366 pixels 


768 pixels 
I 


If you're running the program on a device that responds to orientation changes, you can try 
flipping the screen and observe how the numbers change. You can also sweep your finger from the 
left of the screen to invoke the snapped views and then divide the screen between this program and 
another to see how the width value changes. 

You don’t need to set the SizeChanged event handler in XAML. You can set it in code, perhaps 
during the Page constructor: 

this. SizeChanged += OnPageSizeChanged; 

SizeChanged is defined by FromeworkElement and inherited by all descendent classes. Despite 
the fact that SizeChanged EventArgs derives from RoutedEventArgs, this is not a routed event. You 
can tell it’s not a routed event because the OriginolSource property of the event arguments is always 
null] there is no SizeChongedEvent property; and whatever element you set this event on, that’s the 
element’s size you get. But you can set SizeChanged handlers on any element. Generally, the order 
the events are fired proceeds down the visual tree: MainPage first (in this example), and then Grid and 
TextBlock. 

If you need the rendered size of an element other than in the context of a SizeChanged handler, 
that information is available from the ActuolWidth and ActuolHeight properties defined by 
FromeworkElement. Indeed, the SizeChanged handler in WhatSize is actually a little shorter when ac¬ 
cessing those properties: 


void OnPageSizeChanged (object sender, SizeChangedEventArgs args) 


widthText.Text = thi s .ActualWi dth.ToString(); 
heightText.Text = this. ActualHeight.ToStringO ; 
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What you probably do not want are the Width and Height properties. Those properties are also 
defined by FrameworkElement, but they have default values of "not a number" or NaN. A program 
can set Width and Height to explicit values (such as in the TextFormatting project in Chapter 2, "XAML 
Syntax”)，but usually these properties remain at their default values and they are of no use in de¬ 
termining how large an element actually is. FromeworkElement also defines MinWidth, MaxWidth, 

Min Height, and MaxHeight properties with default NaN values, but these aren't used very often. 

If you access the Actual Width and ActuolHeight properties in the page’s constructor, however, 
you’ll find they have values of zero. Despite the fact that InitializeComponent has constructed the 
visual tree, that visual tree has not yet gone through a layout process. After the constructor finishes, 
the page gets several events in sequence: 

■ OnNovigotedTo 

■ SizeChonged 

■ LoyoutUpdoted 

■ Loaded 

If the page later changes size, additional SizeChonged events and LayoutUpdoted events are fired. 
LoyoutUpdoted can also be fired if elements are added to or removed from the visual tree or if an 
element is changed so as to affect layout. 

If you need a place to perform initialization after initial layout when all the elements in the visual 
tree have nonzero sizes, the event you want is Loaded. It is very common for a Page derivative to 
attach a handler for the Loaded event. Generally, the Loaded event occurs only once during the 
lifetime of a Page object. I say "generally” because if the Page object is detached from its parent (a 
Frame) and reattached, the Loaded event will occur again. But this won’t happen unless you deliber¬ 
ately make it happen. Also, the Unloaded event can let you know if the page has been detached from 
the visual tree. 

Every FromeworkElement derivative has a Loaded event. As a visual tree is built, the Loaded events 
occur in a sequence going up the visual tree, ending with the Page derivative. When that Page ob¬ 
ject gets a Loaded event, it can assume that all its children have fired their own Loaded events and 
everything has been correctly sized. 

Handling a Loaded event in a Page class is so common that some programmers perform Loaded 
processing right in the constructor using an anonymous handler: 


public MainPage() 

{ 

this .InitializeComponentC); 

Loaded += (sender, args)=> 
{ 

}； 

} 
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Sometimes Windows 8 applications need to know when the orientation of the screen changes. 

In Chapter 1, "Markup and Code," I showed an InternationalHelloWorld program that looks fine in 
landscape mode but probably results in overlapping text if switched to portrait mode. To fix that, the 
ScalablelnternationalHelloWorld program code-behind file changes the page’s Font Size property to 
24 in portrait mode: 


Project: ScalablelnternationalHelloWorld I File: MainPage.xaml.es 

public sealed partial class MainPage : Page 
{ 

public MainPage() 

{ 

this. InitializeComponent(); 

SetFontO ; 

DisplayProperties .OrientationChanged += OnDisplayPropertiesOrientationChanged; 

} 

void OnDisplayPropertiesOrientati onChanged(object sender) 

{ 

SetFontO ; 

} 

void SetFontO 
{ 

bool isLandscape = 

DisplayProperties .CurrentOrientation == DisplayOrientations .Landscape || 

DisplayProperties .CurrentOrientation == DisplayOrientations •LandscapeFlipped; 

this. FontSize = isLandscape ? 40 : 24; 

} 

} 

The DisployProperties class and DisployOrientotions enumeration are defined in the Windows 
.Graphics.Display namespace. DisplayProperties.OrientotionChongecJ is a static event, and when 
that event is fired, the static DisplayProperties.CurrentOrientation property provides the current 
orientation. 


Somewhat more information, including snapped states, is provided by the ViewStateChanged 
event of the AppicationView class in the Win do ws. Ul. ViewMonog em en t namespace, but working with 
this event must await Chapter 12, "Pages and Navigation." 


Bindings to Run? 


In Chapter 2 I discussed data bindings. Data bindings can link properties of two elements so that 
when a source property changes, the target property also changes. Data bindings are particularly 
satisfying when they eliminate the need for event handlers. 

Is it possible to rewrite WhatSize to use data bindings rather than a SizeChonged handler? It’s 
worth a try. 
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In the WhatSize project, remove the OnPogeSizeChanged handler from the MainPage.xaml.es file 
(or just comment it out if you don’t want to do too much damage to the file). In the root tag of the 
MainPage.xaml file, remove the SizeChonged attribute and give Main Page a name of "page.” Then, 
set Binding markup extensions on the two Run objects referencing the Actual Width and ActualHeight 
properties of the page: 

<Page … 

FontSize="36" 

Name="page"> 


<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

<TextBlock HorizontalAli gnment="Center" 

VerticalA1i gnment="Top"> 

&#x21A4; 

<Run Text="{Binding El ementName=page , Path=Actual Width}” /> 
pixels &#x21A6; 

</TextBlock> 

<TextBlock HorizontalAli gnment="Center" 

VerticalAli gnment="Center" 

TextAli gnment="Center"> 

&#x21A5; 

<LineBreak /> 

<Run Text="{Binding El ementName=page , Path=Actual Height}" /> pixels 
<LineBreak /> 

&#x21A7; 

</TextBlock> 

</Gri d> 

</Page> 

The program compiles fine, and it runs smoothly without any run-time exceptions. The only 
problem is: Where the numbers should appear is a discouraging 0. 


This is likely to seem odd, particularly when you set the same bindings on the Text property of 
TextBlock instead of Run: 


<Page … 

FontSize="36" 

Name="page"> 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<TextBlock HorizontalAli gnment="Center" 

VerticalAli gnment="Top" 

Text="{Binding El ementName=page , Path=ActualWi dth}" /> 

<TextBlock HorizontalAli gnment="Center" 

VerticalA1i gnment="Center" 

TextAli gnment="Center" 

Text="{Binding El ementName=page , Path=Actual Height}" /> 

</Gri d> 

</Page> 


88 PART: Elementals 


This works: 


1366 


768 


At least it appears to work at first. With the version of Windows 8 that I’m using to write this 
chapter, the numbers are not updated as you change the orientation or size of the page, and they 
really should be. In theory, a data binding is notified when a source property changes so that it can 
change the target property, but the application source code appears to have no event handlers and 
no moving parts. This is what is supposed to make data bindings so great. 

Unfortunately, by giving up on the bindings to Run we've also lost the informative arrows. So, why 
do the data bindings work (or almost work) on the Text property of TextBlock but not at all on the 
Text property of Run? 

It’s very simple. The target of a data binding must be a dependency property. This fact is obvious 
when you define a data binding in code by using the SetBinding method. That’s the difference: The 
Text property of TextBlock is backed by the TextProperty dependency property, but the Text property 
of Run is not. The Run version of Text is a plain old property that cannot serve as a target for a data 
binding. The XAML parser probably shouldn’t allow a binding to be set on the Text property of Run, 
but it does. 

In Chapter 4 I’ll show you how to use a Stack Pan el to get the arrows back in a version of 
WhatSize that uses data bindings, and in Chapter 16, "Rich Text, "I’ll demonstrate a technique using 
RichTextBlock. 

Timers and Animation 


Sometimes a Windows 8 application needs to receive periodic events at a fixed interval. A clock 
application, for example, probably needs to update its display every second. The ideal class for this 
job is DispotcherTimer. Set a timer interval, set a handler for the Tick event, and go. 
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Here's the XAML file for a digital clock application. It 7 s just a big TextBlock: 

Project: DigitalClock | File: MainPage.xaml (excerpt) 

<Crid Background=" {StaticResource ApplicationPageBackgroundThemeBrush}"> 

<TextBlock Name="txtbl k" 

FontFami ly="Luci da Console" 

FontSize="120" 

Hori zontalAl i gnment="Center" 

VerticalA1i gnment="Center" /> 

</Grid> 

The code-behind file creates the DispotcherTimer with a 1-second interval and sets the Text 
property of the TextBlock in the event handler: 

Project: DigitalClock I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

public MainPageC) 

{ 

this. InitializeComponent(); 

DispatcherTimer timer = new DispatcherTimerC) ; 

timer.Interval = TimeSpan .FromSeconds(l); 
timer.Tick += OnTimerTick; 
timer.Start(); 

} 

void OnTimerTi ck(object sender, object e) 

{ 

txtblk.Text = DateTime.Now.ToStri ng("h :mm:ss tt") ; 

} 

} 

And here it is: 


7:43:14 PM 
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Calls to the Tick handler occur in the same execution thread as the rest of the user interface, so if 
the program is busy doing something in that thread, the calls won’t interrupt that work and might 
become somewhat irregular and even skip a few beats. In a multipage application, you might want to 
start the timer in the OnNovigotedTo override and stop it in OnNovigotedFrom to avoid the program 
wasting time doing work when the page is not visible. 

This is a good illustration of the difference in how a desktop Windows application and a Windows 
8 application update the video display. Both types of applications use a timer for implementing a 
clock, but rather than drawing and redrawing text every second by invalidating the contents of the 
window, the Windows 8 application changes the visual appearance of an existing element simply by 
changing one of its properties. 


You can set the DispatcherTimer for an interval as low as you want, but you're not going to get 
calls to the Tick handler faster than the frame rate of the video display, which is probably 60 Hertz 
or about a 17-millisecond period. Of course, it doesn’t make sense to update the video display faster 
than the frame rate. Updating the display precisely at the frame rate gives you as smooth an anima¬ 
tion as possible. If you want to perform an animation in this way, don’t use DispatcherTimer. A better 
choice is the static CompositionTorget.Rendering event, which is specifically designed to be called prior 
to a screen refresh. 

Even better than CompositionTorget.Rendering are all the animation classes provided as part of the 
Windows Runtime. These classes let you define animations in XAML or code, they have lots of options, 
and some of them are performed in background threads. 


But until I cover the animation classes in Chapter 9, "Animation" — and perhaps even after I do — 
the CompositionTorget Rendering event is well suited for performing animations. These are sometimes 
called "manual" animations because the program itself has to carry out some calculations based on 
elapsed time. 


Here’s a little project called ExpandingText that changes the FontSize of a Text Block in the 
CompositionTorget Rendering event handler, making the text larger and smaller. The XAML file simply 
instantiates a TextBlock: 


Project: ExpandingText I File: MainPage.xaml (excerpt) 

<Grid Background=” {StaticResource ApplicationPageBackgroundThemeBrush}"> 

<TextBlock Name="txtbl k" 

Text="Hello, Windows 8!" 

HornzontalAli gnment="Center" 

VerticalAli gnment="Center" /> 

</Grid> 

In the code-behind file, the constructor starts a CompositionTorget Rendering event simply by 
setting an event handler. The second argument to that handler is defined as type object, but it is 
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actually of type RenderingEventArgs, which has a property named RenderingTime of type TimeSpon, 
giving you an elapsed time since the app was started: 


Project: ExpandingText I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

public MainPage() 

{ 

this.InitializeComponent(); 

CompositionTarget .Rendering += OnCompositionTargetRendering; 

} 

void OnCompositionTargetRendering(object sender, object args) 

{ 

RenderingEventArgs renderArgs = args as RenderingEventArgs ; 

double t = (0.25 * renderArgs.RenderingTime.TotalSeconds) % 1; 
double scale = t < 0.5 ? 2 * t : 2 - 2 * t; 
txtblk.FontSize = 1 + scale * 143; 



I’ve attempted to generalize this code somewhat. The calculation of t causes it to repeatedly 
increase from 0 to 1 over the course of 4 seconds. During those same 4 seconds, the value of scale 
goes from 0 to 1 and back to 0, so Font Size ranges from 1 to 144 and back to 1. (The code ensures 
that the Font Size is never set to zero, which would raise an exception.) When you run this program, 
you might see a little jerkiness at first because fonts need to be rasterized at a bunch of different 
sizes. But after it settles into a rhythm, it’s fairly smooth and there is definitely no flickering. 

It’s also possible to animate color, and 111 show you two different ways to do it. The second 
way is better than the first, but I want to make a point here, so here’s the XAML file for the 
ManualBrushAnimation project: 


Project: ManualBrushAnimation I File: MainPage.xaml (excerpt) 

<Grid Name="contentGri d"> 

<TextBlock Name="txtbl k" 

Text="Hel lo, Windows 8!" 

FontFami1 y="Ti mes New Roman" 

FontSi ze="96" 

FontWei ght="Bold" 

Horn' zontalAli gnment="Center" 

VerticalAli gnment="Center" /> 

</Crid> 


Neither the Grid nor the TextBlock have explicit brushes defined. Creating those brushes based on 
animated colors is the job of the CompositionTorget.Rendering event handler: 


Project: ManualBrushAnimation | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

public MainPageC) 

{ 

this. InitializeComponent(); 

CompositionTarget .Rendering += OnCompositionTargetRendering; 

} 
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void OnCompositionTargetRenderi ngCobject sender, object args) 


RenderingEventArgs renderingArgs = args as RenderingEventArgs ; 

double t = (0.25 * renderingArgs.RenderingTime.Total Seconds) % 1; 
t=t<0.5?2*t:2-2*t; 

// Background 

byte gray = (byte) (255 * t); 

Color clr = Color. FromArgb(255, gray, gray, gray); 
contentGrid.Background = new SolidColorBrush(cl r); 

// Foreground 

gray = (byte) (255 - gray); 

clr = Color. FromArgb(255, gray, gray, gray); 

txtblk.Foreground = new SolidColorBrush(cl r); 



As the background color of the Grid goes from black to white and back, the foreground color of 
the TextBlock goes from white to black and back, meeting halfway through. 

The effect is nice, but notice that two SolidColorBrush objects are being created at the frame rate 
of the video display (which is probably about 60 times a second) and these objects are just as quickly 
discarded. This is not necessary. A much better approach is to create two SolidColorBrush objects 
initially in the XAML file: 


Project: ManualColorAnimation | File: MainPage.xaml (excerpt) 

<Gri d> 

<Grid.Background 〉 

〈SolidColorBrush x : Name="gridBrush" /> 
</Grid.Background 〉 


〈TextBlock Text="Hel lo, Windows 8!" 

FontFami1 y="Ti mes New Roman" 

FontSi ze="96" 

FontWei ght="Bold" 

HornzontalAli gnment="Center" 

VerticalAli gnment="Center"> 
<TextBlock.Foreground> 

〈SolidColorBrush x:Name="txtbl kBrush" /> 
</TextBlock.Foreground> 

</TextBlock> 

</Grid> 


These SolidColorBrush objects exist for the entire duration of the program, and they are given names 
for easy access from the CompositionTorget.Rendering handler: 


Project: ManualColorAnimation | File: MainPage.xaml.es (excerpt) 

void OnCompositionTargetRenderi ngCobject sender, object args) 

{ 

RenderingEventArgs renderingArgs = args as RenderingEventArgs ; 

double t = (0.25 * renderingArgs.RenderingTime.TotalSeconds) % 1; 
t=t<0.5?2*t : 2 - 2 * t; 
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// Background 

byte gray = (byte) (255 * t); 

gridBrush.Color = Color. FromArgb(255, gray, gray, gray); 


// Foreground 

gray = (byte) (255 - gray); 

txtblkBrush.Color = Color. FromArgb(255, gray, gray, gray); 

} 

At first this might not seem a whole lot different because two Color objects are being created and 
discarded at the video frame rate. But it’s wrong to speak of objects here because Color is a structure 
rather than a class. It is more correct to speak of Color values. These Color values are stored on the 
stack rather than requiring a memory allocation from the heap. 

It’s best to avoid frequent allocations from the heap whenever possible, and particularly at the rate 
of 60 times per second. But what I like most about this example is the idea of SolidColorBrush objects 
remaining alive in the Windows Runtime composition system. This program is effectively reaching 
down into that composition layer and changing a property of the brush so that it renders differently. 

This program also illustrates part of the wonders of dependency properties. Dependency 
properties are built to respond to changes in a very structured manner. As you’ll discover, the built-in 
animation facilities of the Windows Runtime can target only dependency properties, and "manual" 
animations using CompositionTorget.Rendering have pretty much the same limitation. Fortunately, 
the Foreground property of TextBlock and the Background property of Grid are both dependency 
properties of type Brush, and the Color property of the SolidColorBrush is also a dependency 
property. 

Indeed, whenever you encounter a dependency property, you might ask yourself, "How can I 
animate that?” For example, the Offset property in the GrodientStop class is a dependency property, 
and you can animate it for some interesting effects. 

Here’s the XAML file for the RainbowEight project: 


Project: RainbowEight I File: MainPage.xaml (excerpt) 


<Grid Background=” {StaticResource ApplicationPageBackgroundThemeBrush}"> 
<TextBlock Name="txtbl k" 

Text="8" 

FontFami ly="CooperBl ack" 

FontSize="l" 


HorizontalAli gnment="Center"> 

<TextBlock.Foreground 〉 

<LinearGradientBrush x:Name="gradi entBrush% 
<GradientStop 0ffset="0.00" Color="Red" /> 
<CradientStop 0ffset="0 .14" Color="Orange" /> 
<GradientStop 0ffset="0. 28" Color="Yellow" /> 
<GradientStop 0ffset="0.43" Color="Green" /> 
<GradientStop 0ffset="0. 57" Color="Blue" /> 
<GradientStop 0ffset="0. 71" Color="Indigo" /> 
<CradientStop 0ffset="0 .86" Color="Violet" /> 
<CradientStop 0ffset="1.00" Color="Red" /> 
<GradientStop Offset="l. 14" Color="Orange" /> 
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<GradientStop Offset="l. 28" 
<GradientStop 0ffset="1.43" 
<GradientStop Offset="l. 57" 
<GradientStop Offset="l. 71" 
<GradientStop Offset="l. 86" 
<GradientStop 0ffset="2 .00" 
</LinearGradientBrush> 


Color="Yel low" /> 
Color="Green" /> 
Color="Blue" /> 
Color="Indigo" /> 
Color="Violet" /> 
Color="Red" /> 


</TextBlock.Foreground> 
</TextBlock> 

</Grid> 


A bunch of those GradientStop objects have Offset values above 1, so they’re not going to be visible. 
Moreover, the TextBlock itself won't be very obvious because it has a Fontsize of 1. However, during 
its Loaded event, the Page class obtains the ActualHeight of that tiny TextBlock and saves it in a field. It 
then starts a CompositionTorget.Rendering event going: 


Project: RainbowEight I File: MainPage.xaml (excerpt) 

public sealed partial class MainPage : Page 

{ 

double txtblkBaseSize; // ie, for 1-pixel FontSize 

public MainPage() 

{ 

this. InitializeComponent(); 

Loaded += OnPageLoaded; 

} 

void OnPageLoaded (object sender, RoutedEventArgs args) 

{ 

txtblkBaseSize = txtblk.Actual Height; 

CompositionTarget .Rendering += OnCompositionTargetRendering; 


void OnCompositionTargetRenderi ngCobject sender, object args) 

{ 

// Set FontSize as large as it can be 

txtblk.FontSize = this .ActualHeight / txtblkBaseSize; 

// Calculate t from 0 to 1 repetitively 

RenderingEventArgs renderingArgs = args as RenderingEventArgs ; 

double t = (0.25 * renderingArgs■RenderingTime.TotalSeconds) % 1; 

// Loop through GradientStop objects 

for (i nt index = 0; index < gradientBrush.GradientStops.Count; index++) 
gradientBrush.GradientStops[index].Offset = index / 7.0 - t; 



In the CompositionTorget. Rendering handler, the Fonts ize of the TextBlock is increased based on 
the ActualHeight property of the Page, rather like a manual version of Viewbox. It won’t be the full 
height of the page because the ActualHeight of the TextBlock includes space for descenders and 
diacriticals, but it will be as large as is convenient to make it, and it will change when the display 
switches orientation. 
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Moreover, the CompositionTorget.Rendering handler goes on to change all the Offset properties of 
the LineorGrodientBrush for an animated rainbow effect that I’m afraid can’t quite be rendered on the 
static page of this book: 



You might wonder: Isn’t it inefficient to change the Font Size property of the Text Block at the frame 
rate of the video display? Wouldn’t it make more sense to set a SizeChanged handler for the Page and 
do it then? 

Perhaps a little. But it is another feature of dependency properties that the object doesn’t register 
a change unless the property really changes. If the property is being set to the value it already is, 
nothing happens, as you can verify by attaching a SizeChanged handler on the Text Block itself. 
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CHAPTER 4 


Presentation with Panels 


A Windows Runtime program generally consists of one or more classes that derive from Page. 

Each page contains a visual tree of elements connected in a parent-child hierarchy. A Page 
object can have only one child set to its Content property, but in most cases this child is an 
instance of a class that derives from Panel. Panel defines a property named Children that is of type 
UlElementCollection — a collection of UlElement derivatives, including other panels. 

These Panel derivatives form the core of the Windows Runtime dynamic layout system. As the 
size or orientation of a page changes, panels can reorganize their children to optimally fill the 
available space. Each type of panel arranges its children differently. The Grid, for example, arranges its 
children in rows and columns. The StackPonel stacks its children either horizontally or vertically. The 
VoriobleSizedWropGrid also stacks its children horizontally or vertically but then uses additional rows 
or columns if necessary, much like the Windows 8 start screen. The Canvas allows its children to be 
positioned at specific pixel locations. 

What makes a layout system complex is balancing the conflicting needs of parents and children. 

In part, a layout system needs to be "child-driven” in that each child should be allowed to determine 
how large it needs to be, and to obtain sufficient screen space for itself. But the layout system also 
needs to be "parent-driven.” At any time, the page is fixed in size and cannot give its descendents in 
the visual tree more space than it has available. 

Similar concepts are well known in the Web world. For example, a simple HTML page has a width 
that is parent-driven because it’s constrained by the width of the video display or the browser 
window. However, the height of a page is child-driven because it depends on the content of the page. 
If that height exceeds the height of the browser window, scrollbars are required. 

In contrast, the Windows 8 start screen is the other way around: The number of application tiles 
that can fit vertically is parent-driven because it’s based on the height of the screen. The width of this 
tile display is child-driven. If tiles extend off the screen horizontally, they must be moved into view by 
scrolling. 


The Border Element 


Two of the most important properties connected with layout are HorizontalAlignment and 
VerticolAlignment. These properties are defined by FrameworkElement and set to members of 
enumerations with identical names: HorizontalAlignment and VerticolAlignment. 
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As you saw in Chapter 3, "Basic Event Handling," the default values of Horizontal Alignment 
and Vertical A lign ment are not Left and Top. They are instead HorizontolAlignment. Stretch and 
Vertical Align merit. Stretch. These default Stretch settings imply parent-driven layout: Elements auto¬ 
matically stretch to become as large as their parents. This is not always visually apparent, but in the 
last chapter you saw how a TextBlock stretched to the size of its parent gets all the Tapped events 
anywhere within that parent. 

When the HorizontolAlignment or VerticalAlignment properties are set to values other than Stretch, 
the element sets its own width or height based on its content. Layout becomes more child-driven. 

The important role of HorizontolAlignment and VerticalAlignment also becomes apparent when 
you start adding more parents and children to the page. For example, suppose you want to display a 
TextBlock with a border around it. You might discover (perhaps with some dismay) that TextBlock has 
no properties that relate to a border. However, the Windows.Ul.Xaml.Controls namespace contains a 
Border element with a property named Child. So, you put the TextBlock in a Border and put the Border 
in the Grid, like so: 

Project: NaiveBorderedText | File: MainPage.xaml (excerpt) 

<Page … > 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

〈Border BorderBrush="Red" 

BorderThi ckness="12" 

CornerRadi us="24" 

Background="Yel low"> 

〈TextBlock Text="Hel lo Windows 8!" 

FontSize= ,, 96" 

Foreground="Bl ue" 

HorizontalAli gnment="Center" 

VerticalAl ignment="Center" /> 

</Border> 

</Gri d> 

</Page> 

The BorderThickness property defined by Border can be set to different values for the four sides. 
Just specify four different values in the order left, top, right, and bottom. If you specify only two 
values, the first applies to the left and right and the second applies to the top and bottom. The 
CornerRocJius property defines the curvature of the corners. You can set it a uniform value or four 
different values in the order upper-left, upper-right, lower-right, and lower-left. 
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Notice the Horizon to I A lign ment and Vertical A lign merit properties set on the TextBlock. The markup 
looks reasonable, but the result is probably not what you want: 



Because Border derives from FrameworkElement, it also has HorizontolAlignment and 
VerticolAlignment properties, and their default values are Stretch, which causes the size of the Border 
to be stretched to the size of its parent. To get the effect you probably want, you need to move the 
Horizon to I A lign men t and Vertical A lign men t settings from the TextBlock to the Border: 


Project: BetterBorderedText I File: MainPage.xaml (excerpt) 

<Grid Background="{StaticResource ApplicationPageBackgroundThemeBrush}"> 

〈Border BorderBrush="Red" 

BorderThi ckness="12" 

CornerRadi us="24" 

Background:" Yellow" 

HorizontalA1i gnment="Center" 

VerticalAli gnment="Center"> 

〈TextBlock Text="Hello Windows 8!" 

FontSize="96" 

Foreground="Bl ue" 

Margin="24" /> 

</Border> 


</Grid> 
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IVe also added a quarter-inch margin to the Text Block by setting its Margin property. This causes 
the Border to be a quarter-inch larger than the size of the text on all four sides: 



The Margin property is defined by FrameworkElement, so it is available on every element. The 
property is of type Thickness (the same as the type of the BorderThickness property) — a structure with 
four properties named Left, Top, Right, and Bottom. Margin is exceptionally useful for defining a little 
breathing room around elements so that they don’t butt up against each other, and it appears a lot in 
real-life XAML. Like BorderThickness, Margin can potentially have four different values. In XAML, they 
appear in the order left, top, right, and bottom. Specify just two values and the first applies to the left 
and right, and the second to the top and bottom. 

In addition, Border defines a Podding property, which is similar to Margin except that it applies to 
the inside of the element rather than the outside. Try removing the Margin property from TextBlock 
and instead set Padding on the Border: 

〈Border BorderBrush="Red" 

BorderThi ckness="12" 

CornerRadi us="24" 

Background:" Yellow" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Center" 

Padding= ,, 24"> 

<TextBlock Text="Hel lo Windows 8!" 


FontSize="96" 
Foreground="Bl ue" /> 


</Border> 


The result is the same. In either case, any HorizontolAlignment or Vertico I A lignment settings on the 
TextBlock are now irrelevant. 
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For layout purposes, Margin is considered to be part of the size of the element, but otherwise it is 
entirely out of the element’s control. The element cannot control the background color of its margin, 
for example. That color depends on the element’s parent. Nor does an element get user input from 
the margin area. If you tap in an element’s margin area, the element’s parent gets the Topped event. 

The Padding property is also of type Thickness, but only a few classes define a Podding property: 
Control, Border, TextBlock, RichTextBlock, and RichTextBlockOverflow. The Padding property defines an 
area inside the element. This area is considered to be part of the element for all purposes, including 
user input. 

If you want a TextBlock to respond to taps not only on the text itself but also within a 100-pixel 
area surrounding the text, set the Padding property of the TextBlock to 100 rather than the Margin 
property. 

Rectangle and Ellipse 

As you saw in Chapter 2, "XAML Syntax,” the Windows.Ul.Xoml.Shapes namespace contains classes 
used to render vector graphics: lines, curves, and filled areas. The Shape class itself derives from 
FrameworkElement and defines various properties, including Stroke (for specifying the brush used 
to render straight lines and curves), StrokeThickness, and Fill (for specifying the brush used to render 
enclosed areas). 

Six classes derive from Shape. Line, Polyline, and Polygon render straight lines based on coordinate 
points, and Path uses a series of classes in Windows.Ul.Xaml.Media for rendering a series of straight 
lines, arcs, and Bezier curves. 

The remaining two classes that derive from Shape are Rectangle and Ellipse. Despite the innocent 
names, these elements are real oddities in that they define figures without the use of coordinate 
points. Here, for example, is a tiny piece of XAML to render an ellipse: 


Project: SimpleEllipse I File: MainPage.xaml (excerpt) 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
〈Ellipse Stroke="Red" 

StrokeThi ckness="24" 

Fill="Blue" /> 

</Grid> 
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Notice how the ellipse fills its container: 



Like all other FrameworkElement derivatives, Ellipse has default HorizontalAlignment and 
Vertical A lignmen t settings of Stretch, but more than most other elements, Ellipse unashamedly flaunts 
the implications of these settings. 


What happens if you set a nondefault HorizontolAlignment or VerticalAlignment on this Ellipse 
element? Try it! The ellipse shrinks down to nothing. It disappears. In fact, it’s hard to imagine how it 
can legitimately have any other behavior. If you do not want the Ellipse or Rectangle element to fill its 
container, your only real alternative is to set explicit Height and Width values on it. 

The Shape class also defines a Stretch property (not to be confused with the Stretch values of 
Ho rizon ta I A lignment and VerticalAlignment), which is similar to the Stretch property defined by Image 
and Viewbox. For example, in the SimpleEllipse program, if you set the Stretch property to Uniform, 
you'll get a special case of an ellipse that has equal horizontal and vertical radii. This is a circle, and 
its diameter is set to the minimum of the container’s width and height. Setting the Stretch property 
to UniformToFill also gets you a circle, but now the diameter is the moximum of the container's width 
and height, so part of the circle is cropped: 
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You can control what part is cropped with the HorizontolAlignment and VerticolAlignment properties. 

Rectangle is very similar to Ellipse and also shares several characteristics with Border, although the 
properties have different names: 


Border 

Rectangle 

BorderBrush 

Stroke 

BorderThickness 

StrokeThickness 

Background 

Fill 

CornerRadius 

RadiusX / RadiusY 


The big difference between Border and Rectangle is that Border has a Child property and Rectangle 
does not 

The StackPanel 


Panel and its derivative classes form the core of the Windows Runtime layout system. Panel defines 
just a few properties on its own, but one of them is Children, and that’s crucial. A Panel derivative is 
the only type of element that supports multiple children. 

This class hierarchy shows Panel and some of its derivatives: 

Object 

DependencyObject 

UlElement 

FrameworkElement 

Panel 

Canvas 

Grid 

Stack Pan el 

VariobleSizedWropGricJ 

There are others, but they have restrictions that prevent them from being used except in controls 
of type ItemsControl (which I’ll discuss in Chapter 11, "The Three Templates"). I’ll save the Grid for 
Chapter 5, "Control Interaction," and I’ll cover the other three here. 

Of these standard panels, the StackPanel is certainly the easiest to use. Like the name suggests, it 
stacks its children, by default vertically. The children can be different heights, but each child gets only 
as much height as it needs. The SimpleVerticalStack program shows how it’s done: 


Project: SimpleVerticalStack I File: MainPage.xaml (excerpt) 

<Crid Background=” {StaticResource ApplicationPageBackgroundThemeBrush}"> 
<StackPanel> 

〈TextBlock Text="Ri ght-Aligned Text" 

FontSize="48" 

HorizontalAli gnment="Ri ght" /> 
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<Image Source="http://www. charlespetzold.com/pw6/PetzoldJersey.jpg" 
Stretch="None" /> 

<TextB"lock Text="Fi gure 1. Petzold heading to the basketball court" 
FontSi ze="24" 

HorizontalAli gnment="Center" /> 

〈Ellipse Stroke="Red" 

StrokeThi ckness="12" 

Fill="Blue" /> 

<TextBlock Text="Left-Al igned Text" 

FontSi ze="36" 

HorizontalAli gnment="Left" /> 

</StackPanel> 

</Grid> 


In XAML the children of the Stock Pan el are simply listed in order, just as they appear on the screen: 


Right-Aligned Text 



Figure 1. Petzold heading to the basketball court 

Left-Aligned Text 


Notice that I made this StackPonel a child of the Grid. Panels can be nested, and they very often 
are nested. In this particular case I could have replaced the Grid with StackPonel and set that same 
Background property on it. 


Each element in the StackPonel gets only as much height as it needs but can stretch to the panel’s 
full width, as demonstrated by the first and last TextBlock aligned to the right and left. In a vertical 
StackPonel, any VerticolAlignment settings on the children are irrelevant and are basically ignored. 


Notice that the Stretch property of the Image element is set to None to display the bitmap in 
its pixel dimensions. If left at its default value of Uniform, the Image is stretched to the width of 
the StockPanel (which is the same as the width of the Page) and its vertical dimension increases 
proportionally. This might cause all the elements below the Image to be pushed right off the bottom 
of the screen and into the bit bucket. 


The XAML also includes an Ellipse. What happened to it? Like all the other children of the 
StockPanel, the Ellipse is given only as much vertical space as it needs, and it really doesn’t need 
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any, so it shrinks to nothing. If you want the Ellipse to be visible, give it at least a nonzero Height, for 
example, 48: 


Right-Aligned Text 



Figure 1. Petzold heading to the basketball court 

Left-Aligned Text 


If you also set the Stretch property of the Ellipse to Uniform, you’ll get a circle rather than a very wide 
ellipse. 

This Stock Pan el occupies the entire page. How do I know this? When experimenting with panels, 
one very useful technique is to give each panel a unique Background so that you can see the footprint 
that the panel occupies on the screen. For example: 


〈StackPanel Background="Bl ue"> 

Like all other FromeworkE lement derivatives, StockPonel also has Horizon to I A lign men t and 
VerticalAlignment properties. When set to nondefault values, these properties cause the StockPanel to 
tightly hug its children (so to speak), and the change can be dramatic. Here's what it looks like with the 
StockPanel getting a Background of Blue and Horizon to I A tig nm en t and Vertical A lign men t values of Center: 



Figure 1. Petzold heading to the basketball court 


Left-Aligned Text 
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The width of the StockPonel is now governed by the width of its widest child, which is the totally 
honest caption under the photograph. 


Horizontal Stacks 


It is also possible to use StockPonel to stack elements horizontally by setting its Orientation property 
to Horizontal. The SimpleHorizontalStack program shows an example: 


Project: SimpleHorizontalStack I File: MainPage.xaml (excerpt) 

<Grid Background=" {StaticResource ApplicationPageBackgroundThemeBrush}"> 

<StackPanel Orientati on="Hori zontal" 

VerticalAli gnment="Center" 

HorizontalA1i gnment="Center"> 

<TextBlock Text="Rectangl e:" 

VerticalA1i gnment="Center" /> 

〈Rectangle Stroke="Bl ue" 

FilWRed” 

Width="72" 

Height="72" 

Margin="12 0" 

VerticalAli gnment="Center" /> 

<TextBlock Text="El 1ipse:" 

VerticalAli gnment="Center" /> 

〈Ellipse Stroke="Red" 

Fill="Blue" 

Width="72" 

Height="72" 

Margin="12 0" 

VerticalAli gnment="Center" /> 

<TextBlock Text="Petzol d:" 

VerticalAli gnment="Center" /> 

<Image Sou rce="http: //www.charlespetzold.com/pw6/PetzoldJersey.jpg" 
Stretch="Uni form" 

Width= M 72" 

Margin="12 0" 

VerticalAli gnment="Center" /> 


</StackPanel> 
</Grid> 
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Here it is: 



You might question the apparently excessive number of alignment settings. Try removing all the 
VerticolAlignment and Horizontal Alignment settings, and the result looks like this: 



The StockPanel is now occupying the entire page, and each of the individual elements occupies the 
full height of the StockPanel. TextBlock aligns itself at the top, and the other elements are in the 
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center. Setting the HorizontalAlignment and Vertical A lignmen t settings of the Panel to Center tightens 
up the space that the panel occupies and moves it to the center of the display, like this: 



The height of the Stock Pan el is now governed by the height of its tallest element, but all the elements 
are stretched to that height. To center all the elements relative to each other, the easiest approach is 
to give them all VerticalAlignment settings of Center. 

WhatSize with Bindings (and a Converter) 

In Chapter 3 I discussed how the WhatSize program couldn’t accommodate a data binding because 
the Text property in the Run class isn't a dependency property. Only dependency properties can be 
targets of data bindings. 

Fortunately, for single lines of text, you can mimic multiple Run objects with multiple TextBlock 
elements in a horizontal StackPanel. Here’s WhatSizeWithBindings: 

Project: WhatSizeWithBindings I File: MainPage.xaml (excerpt) 

<Page 

x:Cl ass="WhatSi zeWithBindings.Mai nPage" 

FontSize="36" 

Name="page"> 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

<StackPanel Orientati on="Hori zontal" 

HorizontalA1i gnment="Center" 

VerticalAli gnment="Top"> 

〈TextBlock Text="&#x21A4 ; " /> 

<TextBlock Text="{Binding El ementName=page , Path=ActualWi dth}" /> 

〈TextBlock Text=" pixels &#x21A6;" /> 

</StackPanel> 
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<StackPanel HorizontalAli gnment="Center" 

VerticalAli gnment="Center"> 

<TextBlock Text="&#x21A5 ;" TextAli gnment="Center" /> 

<StackPanel Orientati on="Hori zontal" 

HorizontalAli gnment="Center"> 

<TextBlock Text="{Bi nding El ementName=page , Path=Actual Height}" /> 
<TextBlock Text=" pixels" /> 

</StackPanel> 


<TextBlock Text="&#x21A7 ;" TextAli gnment="Center" /> 

</StackPanel> 

</Gri d> 

</Page> 

Notice that the root element is now given a name of page, which is referenced in the two data 
bindings to obtain the ActuolWidth and ActuolHeight properties. The big advantage over the previous 
version is that there’s no longer any need for an event handler in the code-behind file. And here it is: 


<■<1366 pixels h 


768 pixels 
I 


Although the values are initially correct, the bindings in the Windows 8 version that I’m using for 
this chapter unfortunately don’t update the values with a different orientation or snap view. 

These data bindings are automatically converting double values to string objects. But what if you 
wanted this conversion to work a little differently? Suppose you want to display a particular number 
of decimal places in the results? Or perhaps, more appropriate for this example, you want a comma 
separator to appear in the width so that it’s 1,366? 

It is possible to customize the data conversion that occurs in a binding by supplying a little piece of 
code to the Binding object. The Binding class has a property named Converter of type IValueConverter, 
an interface with two methods named Convert (to convert from a binding source to a binding target) 
and ConvertBack (for a conversion from the target back to the source in a two-way binding). 
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To create your own custom converter, you'll need to derive a class from IVolueConverter and to fill 
in the two methods. Here’s an example that shows these methods doing nothing: 

public class NothingConverter : IValueConverter 
{ 

public object Convert(object value, Type targetType, object parameter, string language) 

{ 

return value; 

} 

public object ConvertBack (object value, Type targetType, object parameter, string language) 
{ 

return value; 



If you'll be using the binding only in a one-way mode, you can ignore the ConvertBack method. 

In the Convert method, the value argument is the value coming from the binding source. In the 
WhatSize example, this is a double. The TargetType is the type of the target — in the WhatSize example, 
a string. 

If you’re writing a binding converter specifically for WhatSize to convert floating-point numbers to 
strings with comma separators and no decimal points, the Convert method can be as simple as this: 


public object Convert(object value, Type targetType, object parameter, string "language) 

{ 

return C(double)value) .ToStri ng("N0") ; 

} 

But it’s more common to generalize binding converters. For example, it might be useful for the 
converter to handle value arguments of any type that implements the IFormattable interface, which 
includes double as well as all the other numeric types and DoteTime. The IFormattable interface 
defines a ToString method with two arguments: a formatting string and an object that implements 
IFormatProvider, which is generally a Culturelnfo object. 

Besides value and targetType, the Convert method also has parameter and language 
arguments. These come from two properties of the Binding class named ConverterParameter and 
ConverterLanguoge, which are generally set right in the XAML file. This means that the formatting 
specification for ToStri ng can be provided by the parameter argument to Convert, and a Culturelnfo 
object could be created from the language argument. Here’s one possibility: 


Project: WhatSizeWithBindingConverter | File: FormattedStringConverter.es 
using System; 

using System.Globalization; 
using Windows.UI.Xaml.Data; 

namespace WhatSizeWithBindingConverter 
{ 

public cl ass FormattedStringConverter : IValueConverter 
{ 

public object Convert(object value, Type targetType, object parameter, string language) 
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if (value is IFormattable && 
parameter is string && 

! Stri ng. IsNullOrEmptyCparameter as string) && 
targetType == typeof (string)) 

{ 

if (Stri ng ■IsNul10rEmpty(language)) 

return (value as IFormattabl e).ToString(parameter as string ， null); 

return (value as IFormattabl e).ToStringCparameter as string , 

new Culturelnfo(language)); 

} 

return value; 

} 

public object ConvertBack (object value, Type targetType, object parameter, string 
language) 

{ 

return value; 



The Convert method uses ToString only if several conditions are met. If the conditions are not met, the 
fallback is simply to return the incoming value argument. 

In the XAML file, the binding converter is generally defined as a resource so that it can be shared 
among multiple bindings: 


Project: WhatSizeWithBindingConverter | File: MainPage.xaml (excerpt) 
<Page 

x:Cl ass="WhatSi zeWithBindingConverter.Mai nPage" 

FontSize="36" 

Name="page"> 


<Page.Resources 〉 

<local : FormattedStringConverter x:Key="stri ngConverter" /> 
</Page.Resources 〉 


<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<StackPanel Orientati on="Hori zontal" 

HorizontalA1i gnment="Center" 

VerticalAli gnment="Top"> 

<TextBlock Text="&#x21A4 ; " /> 

<TextBlock Text="{Binding El ementName=page , 

Path=ActualWi dth, 

Converter={Stati cResource stringConverter} , 
ConverterPa rameter=N0}" /> 

<TextBlock Text=" pixels &#x21A6;" /> 

</StackPanel > 

<StackPanel HorizontalA1i gnment="Center" 

VerticalAli gnment="Center"> 

〈TextBlock Text="&#x21A5 ;" TextAli gnment="Center" /> 

<StackPanel Orientati on="Hori zontal" 

HorizontalA1i gnment="Center"> 
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<TextBlock Text="{Binding El ementName=page , 

Path=Actual Height, 

Converter={Stati cResource stringConverter} , 
ConverterParameter=NO}" /> 

<TextBlock Text=" pixels" /> 

</StackPanel> 


〈TextBlock Text="&#x21A7 ;" TextAli gnment="Center" /> 

</StackPanel> 

</Gri d> 

</Page> 

Take careful note of the Binding syntax. I’ve spread it out over four lines for purposes of clarity (and 
to stay within the margins of the book page), but notice that the Binding markup extension contains 
an embedded markup extension of StaticResource for referencing the binding converter resource. No 
quotation marks appear within either markup extension. 

Now the width is formatted a little fancier: 


h 1,366 pixels h 


768 pixels 
I 


The ScrollViewer Solution 


What happens if there are too many elements for Stack Pan el to display on the screen? In real life, that 
situation occurs quite often and it’s why a StockPonel with more than just a few elements is almost 
always put inside a ScrollViewer. 

The ScrollViewer has a property named Content that you can set to anything that might be too 
large to display in the space allowed for it — a single large Image, for example. ScrollViewer provides 
scrollbars for the mouse-users among us. Otherwise, you can just move the content around with your 
fingers. By default, ScrollViewer also adds a pinch interface so that you can use two fingers to make 
the content larger or smaller. This can be disabled if you want by setting the Zoom Mode property to 
Disabled. 
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ScrollViewer defines a couple other crucial properties. Most often you’ll be using ScrollViewer 
for vertical scrolling, such as with a vertical StackPanel. Consequently, the default value of the 
VerticolScrollBorVisibility property is the enumeration member ScrollBorVisibility.Visible. This setting 
doesn’t mean that the scrollbar is actually visible all the time. For mouse users, the scrollbar appears 
only when the mouse is moved to the right side of the ScrollViewer, and then it fades from view if the 
mouse is moved away. A much thinner slider appears when you scroll using your finger. 

Horizontal scrolling is different: The default value of HorizontolScrollBarVisibility property is 
Disabled, so you’ll want to change that to enable horizontal scrolling. The other two options are 
Hidden, which allows scrolling with your fingers but not the mouse, and Auto, which is the same as 
Visible if the content requires scrolling and Disabled otherwise. 

The XAML file for the StackPanelWithScrolling program contains a Stock Pan el in a ScrollViewer. 
Notice that the Fontsize property is set in the root tag so that it can be inherited throughout the 
page: 

Project: StackPanelWithScrolling | File: MainPage.xaml (excerpt) 

<Page 

x:Class=" StackPanelWithScrolling.MainPage" 

FontSize="26"> 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

<ScrollViewer> 

〈StackPanel Name="stackPanel " /> 

</ScrollViewer> 

</Grid> 

</Page> 

Now all that's necessary in the code-behind file is to generate so many items for the StackPanel 
that they can’t all be visible at once. Where do we get so many items? One convenient solution is to 
use .NET reflection to obtain all 141 static Color properties defined in the Colors class: 

Project: StackPanelWithScrolling | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

public MainPageO 

{ 

this .Ini ti alizeComponent(); 

IEnumerable<PropertyInfo> properties = 

typeof (Colors) .GetTypelnfoO.DeclaredProperties; 

foreach (Propertylnfo property in properties) 

{ 

Color clr = (Color)property .GetValue(null) ; 

TextBlock txtblk = new TextBlockO ; 

txtblk.Text = String. Format ("{0} \x2014 {l:X2}-{2:X2}-{3:X2}-{4:X2}" , 

property.Name, clr.A, clr.R, clr.G, clr.B); 

StackPanel.Chi Idren.Add(txtblk); 

} 

} 


} 
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Windows 8 reflection works a little differently from .NET reflection. Generally, to get anything 
interesting from the Type object, you need to call a Windows 8 extension method GetTypelnfo. The 
returned Typelnfo object makes available additional information about the Type. In this program, the 
DeclaredProperties property of Typelnfo obtains all the properties of the Colors class in the form of 
Property Info objects. Because all the properties in the Colors class are static, the value of these static 
properties can be obtained by calling GetVolue on each Propertylnfo object with a null parameter. 
Each TextBlock gets the name of the color, an em-dash (Unicode 0x2014), and the hexadecimal color 
bytes. The display looks like this: 


Honeydew — FF-F0-FF-F0 
HotPink —FF-FF-69-B4 
ndianRed —FF-CD-5C-5C 
ndigo —FF-4B-00-82 
vory —FF-FF-FF-FO 
Khaki —FF-F0-E6-8C 
Lavender — FF-E6-E6-FA 
LavenderBlush — FF-FF-F0-F5 
.awnGreen — FF-7C-FC-00 
.emonChiffon — FF-FF-FA-CD 
.ightBlue —FF-AD-D8-E6 
.ightCoral — FF-F0-80-80 
LightCyan — FF-EO-FF-FF 
.ightGoldenrodYellow _ FF-FA-FA-D2 
.ightGray—FF-D3-D3-D3 
.ightGreen — FF-90-EE-90 
.ightPink —FF-FF-B6-C1 
.ightSalmon — FF-FF-A0-7A 
.ightSeaGreen — FF-20-B2-AA 
.ightSkyBlue — FF-87-CE-FA 
.ightSlateGray — FF-77-88-99 
.ightSteelBlue — FF-B0-C4-DE 
.ightYellow—FF-FF-FF-EO 


And, of course, you can scroll it with your finger or the mouse. 


To simplify the use of reflection in the C++ version of this program, the program references a 
ReflectionHelper library in the solution that I wrote in C#. This library is also referenced in some 
subsequent projects in this chapter and other chapters. I’ll discuss libraries later in this chapter. 

As you play around with the program, you’ll discover that the ScrollViewer incorporates a nice fluid 
response to your finger movements, including inertia and bounce. You’ll want to use ScrollViewer for 
virtually all your scrolling needs. You’ll discover that many controls that incorporate scrolling — such 
as the List Box and GridView coming up in Chapter 11 — have this same ScrollViewer built right in. I 
wouldn’t be surprised if this same ScrollViewer is used in the Windows 8 start screen. 

Wouldn’t it be nice to see the actual colors as well as their names and values? That enhancement is 
coming up soon! 

Several times already in this book I’ve shown you partial class hierarchies. If you’ve explored the 
Windows 8 documentation trying to find these class hierarchies, you’ve probably discovered that 
the documentation for each class shows only an ancestor class hierarchy but not derived classes. So, 
how exactly did I create the class hierarchies for this book?. They come from a program I wrote called 
DependencyObjectClassHierarchy, which uses a ScrollViewer and StockPonel to show all the classes 
that derive from DependencyObject. 
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highlightBrush = 

new SolidColorBrush (new UlSetti ngs() .UIE1ementCol or(UIEl ementType .Highlight)); 

The XAML file is similar to the previous one except I’ve specified a smaller font: 

Project: DependencyObjectClassHierarchy | File: MainPage.xaml (excerpt) 

<Page 

x:Cl ass="DependencyObj ectClassHierarchy.MainPage" 

FontSi ze="{StaticResource ControlContentThemeFontSi ze}"> 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

<ScrollViewer> 

〈StackPanel Name="stackPanel " /> 

</Scro"ll Vi ewer> 

</Gri d> 

</Page> 

The program builds a tree of classes and their descendent classes. Each node is a particular class 
and a collection of its immediate descendent classes, so I added another code file to the project for a 
class that represents this node: 

Project: DependencyObjectClassHierarchy | File: ClassAndSubclasses.es 
using System; 

using System.Col1ections.Generic; 

namespace DependencyObjectClassHierarchy 

{ 

class ClassAndSubclasses 

{ 

public ClassAndSubclasses (Type parent) 

{ 

this .Type = parent; 

this .Subclasses = new Li st<Cl assAndSubcl asses>() ; 

} 

public Type Type { protected set ; get ; } 

public Li st<Cl assAndSubcl asses> Subclasses { protected set; get; } 



Just as it’s possible to use reflection to get all the properties defined by a class, you can use 
reflection to get all public classes defined in an assembly. These classes are available from the 
ExportedTypes property of the Assembly object. Conceptually, the entire Windows Runtime is 
associated with a single assembly, so to get a reference to that assembly you just need one type. You 
get the Assembly object from the Assembly property of the Typelnfo object for that type. 

Project: DependencyObjectClassHierarchy I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

Type rootType = typeof (DependencyObject) ; 

Typelnfo rootTypelnfo = typeof (DependencyObject) .GetTypelnfoC); 
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Li st<Type> classes = new Li st<Type>() ; 
Brush highlightBrush; 


public MainPage() 

{ 

this .InitializeComponent(); 
highlightBrush = 

new SolidColo 「 Brush (new UlSetti ngs() .UIE1ementColor (UIE1 ementType _Highlight)); 

// Accumulate all the classes that derive from DependencyObject 
AddToClassLi st(typeof (Windows.Ul.Xaml .DependencyObject)) ; 

// Sort them alphabetically by name 
cl asses.Sort((tl, t2)=> 

{ 

return String .Compare(tl.GetTypelnfoC).Name, t2.GetTypelnfoO.Name); 

}); 

// Put all these sorted classes into a tree structure 
ClassAndSubclasses rootClass = new ClassAndSubclasses(rootType) ; 

AddToTree(rootClass, classes); 

// Display the tree using TextBlock's added to StackPanel 
Display(rootClass, 0); 

} 

void AddToClassList (Type sampleType) 

{ 

Assembly assembly = sampleType.GetTypelnfoO.Assembly; 

foreach (Type type in assembly.ExportedTypes) 

{ 

Typelnfo typelnfo = type.GetTypelnfoO ； 

if (typelnfo.IsPublic && rootTypelnfo.IsAssignableFrom(typelnfo)) 
classes.Add(type); 

} 

} 

void AddToTree(Cl assAndSubclasses parentClass, List<Type> cl asses) 

{ 

foreach (Type type in classes) 

{ 

Type baseType = type.GetTypelnfoO - BaseType; 

if (baseType == parentClass.Type) 

{ 

ClassAndSubclasses subclass = new ClassAndSubclasses(type) ; 

parentClass.Subclasses.Add(subclass); 

AddToTree(subClass, classes); 
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void Display (Cl assAndSubclasses parentClass, int indent) 


Typelnfo typelnfo = parentClass.Type.GetTypelnfoO; 

// Create TextBlock with type name 
TextBlock txtblk = new TextB1ock() ; 

txtblk.Iniines. Add(new Run { Text = new stri ng( ' ' , 8 * indent) }); 
txtblk.Iniines. Add(new Run { Text = typelnfo.Name }); 

// Indicate if the class is sealed 
if (typelnfo.IsSealed) 

txtblk.Iniines.Add (new Run 

{ 

Text = " (sealed)" , 

Foreground = highlightBrush 

}); 

// Indicate if the class can't be instantiated 

IEnumerable<ConstructorInfo> constructorlnfos = typelnfo.DeclaredConstructors; 
int publicConstructorCount = 0; 

foreach (Const ructorlnfo constructorlnfo in constructorlnfos) 
if (constructorlnfo.IsPublic) 
publicConstructorCount += 1; 

i f (publicConstructorCount == 0) 
txtblk.Iniines.Add (new Run 
{ 

Text = " (non-instantiable)" , 

Foreground = highlightBrush 

}); 

// Add to the StackPanel 
stackPanel.Chi Idren.Add(txtblk); 

// Cal 1 this method recursively for all subclasses 

foreach (Cl assAndSubclasses subclass in parentClass.Subclasses) 

Display(subclass, indent + 1); 

} 

} 


Notice how the TextBlock for each class is constructed by adding Run items to its Inlines collection. 
It’s sometimes useful for a class hierarchy to display additional information, so the program also 
checks whether the class is marked as sealed and whether it can be instantiated. In the Windows 
Presentation Foundation and Silverlight, classes that can’t be instantiated are generally defined as 
abstract. In the Windows Runtime, they have protected constructors instead. 
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Here’s the section of the class hierarchy with Panel derivatives: 


ScrollBar (sealed) 

Slider 
RichEditBox 
SemanticZoom (sealed) 

TextBox 

Thumb (sealed) 

ToggleSwitch (sealed) 

UserControl 

Page 

Glyphs (sealed) 

Image (sealed) 

ItemsPresenter (sealed) 

MediaElement (sealed) 

Panel (non-instantiable) 

Canvas 

Grid 

SwapChainBackgroundPanel 

StackPanel 

VariableSizedWrapGrid (sealed) 
VirtualizingPanel (non-instantiable) 
CarouselPanel 
OrientedVirtualizingPanel 
VirtualizingStackPanel 
WrapGrid (sealed) 

Popup (sealed) 

RichTextBlock (sealed) 
RichTextBlockOverflow (sealed) 

Shape (non-instantiable) 

Ellipse (sealed) 

Line (sealed) 

Path 

Polygon (sealed) 

Polyline (sealed) 

Rectangle (sealed) 

TextBlock (sealed) 

TickBar (sealed) 

Viewbox (sealed) 

WebView (sealed) 

VisualState (sealed) 

VisualStateGroup (sealed) 

VisualStateManager 

VisualTransition 


Layout Weirdness or Normalcy? 


Becoming acquainted with the mechanics of layout is an important part of being a crafty Windows 
Runtime developer, and the best way to make this acquaintance is to write your own Panel deriva¬ 
tives. That job awaits us in a Chapter 11, but you can also discover a lot byjust experimenting. 


Suppose you have a StackPanel and you decide that one of the items in this StackPanel should be 
a ScrollViewer with another StackPanel. To determine what happens in such a situation, you might 
experiment with the StackPanelWithScrolling project and change the XAML file like so: 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

<StackPanel> 

〈Scroll Viewer> 

<StackPanel Name="stackPanel " /> 

〈 /ScrollViewer> 

</StackPanel> 

</Gri d> 


When you try it out, you’ll discover it doesn’t work. You can’t scroll. What happened? 

The conflict here results from the different ways in which StackPanel and ScrollViewer calculate 
their desired heights. The StackPanel calculates a desired height based on the total height of all its 
children. In the vertical dimension (by default), StackPanel \s entirely child-driven. To calculate a total 
height, it offers to each of its children an infinite height. (When you write your own Panel derivatives, 
you’ll see that I'm not speaking metaphorically or abstractly. A Double.Positivelnfinity vaIue actually 
comes into play!) The children respond by calculating a desired height based on their natural size. The 
StackPanel adds these heights to calculate its own desired height. 
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The height of the ScrollViewer, however, is parent-driven. Its height is only what its parent offers to 
it, and in our earlier example this was the height of the Grid, which was the height of the Page, which 
was the height of the window. The ScrollViewer is able to determine how to scroll its content because 
it knows the difference between the height of its child (often a Stack Pan el) and its own height. 

Now put a vertically scrolling ScrollViewer as a child of a vertical StackPanel. To determine the 
desired size of this ScrollViewer child, the StackPanel offers it an infinite height. How tall does the 
ScrollViewer really want to be? The height of the ScrollViewer is now child-driven rather than parent- 
driven, and its desired height is the height of its child, which is the total height of the inner StackPanel, 
which is the total accumulated height of all the children in that StackPanel. 

From the perspective of the ScrollViewer, its height is the same as the height of its content, which 
means that there’s nothing to scroll. 

In other words, when a vertically scrolling ScrollViewer is put in a vertical StackPanel, losing the 
ability to scroll is totally expected behavior! 

Here’s another seeming layout oddity that is actually quite normal: Try giving a Text Block a very 
long chunk of text to display, and set the TextWropping property to Wrap. In most cases, the text 
wraps as we might expect. Now put that Text Block in a StackPanel with an Orientation property set 
to Horizontal. To determine how wide the TextBlock needs to be, the StackPanel offers it an infinite 
width, and in response to that infinite width, the TextBlock stops wrapping the text. 

In the WhatSizeWithBindings and WhatSizeWithBindingConverter programs you saw how a 
horizontal StackPanel can effectively concatenate TextBlock elements, one of which has a binding on 
its Text property. But what if you wanted to use this same technique with a paragraph of wrapped 
text? What if you wanted part of the text of this paragraph to be a result of a binding? You can’t do it 
with a horizontal StackPanel because the text will never wrap. You can’t do it with a Run element of a 
TextBlock because the Text property of Run is not backed by a dependency property. The solution, of 
course, is to set that item from code. Another solution involves RichTextBlock, as youll see in Chapter 
16, "Rich Text." 

A horizontal StackPanel can't impose text wrapping on child TextBlock elements, but a vertical 
StackPanel can. A vertical StackPanel has a finite width, so it’s an ideal host for TextBlock elements that 
wrap text, as you’ll see next. 

Making an E-Book 

A TextBlock item that goes into a vertical StackPanel can have its Textwrapping property set to Wrap, 
which means that it can actually be a whole paragraph rather than just a word or two. Image elements 
can also go into this same StackPanel, and the result can be a rudimentary illustrated e-book. 

On the famous Project Gutenberg website, I found an illustrated version of Beatrix Potter’s classic 
children’s book The Tale of Tom Kitten (http://www.gutenberg.org/ebooks/14837), so I created a Visual 
Studio project named TheTaleOfTomKitten and I made a folder in that project called Images. From 
Project Gutenberg’s HTML version of the book, it was easy to download all the illustrations in the 
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form of JPEG files. These have names such as tomxx.jpg, where xx is the original page number of the 
book where that illustration appeared. From within the Visual Studio project, I then added all 28 of 
these JPEG files to the Images folder. 

Most of the rest of the work involved the MainPage.xaml file. Each paragraph of the book became 
a TextBlock, and these I interspersed with Image elements referencing the JPEG files in the Images 
folder. 

However, I felt it necessary to deviate somewhat from the ordering of the text and images in 
Project Gutenberg’s HTML file. A PDF of the original edition of The Tale of Tom Kitten on the Internet 
Archive site [http://archive.org/details/tdeoftomkittenOOpottuoft') reveals how Miss Potter’s illustrations 
are associated with the text of the book. There are two patterns: 

1. Text appears on the verso (left-hand, even-numbered) page with an accompanying illustration 
on the recto (right-hand, odd-numbered) page. 

2. Text appears on the recto page with an accompanying illustration on the verso page. 

Adapting this paginated book to a continuous format required altering the order of the text and 
image in this second case so that the text appears before the accompanying illustration. That’s why 
you’ll see some page swaps in the XAML file. 

Given the very many Text Block and Image elements, styles seemed almost mandatory: 


Project: TheTaleOfTomKitten | File: MainPage.xaml (excerpt) 


<Page.Resources 〉 

<Style x : Key="commonTextStyl e" TargetType="TextBlock"> 

<Setter Property="FontFamily" Val ue="Century School book" /> 
〈Setter Property="FontSi ze" Value="36" /> 

〈Setter Property=" Foreground" Val ue="Bl ack" /> 

〈Setter Property="Margi n" Val ue="0 12" /> 

</Style> 


<Style x : Key="paragraphTextStyl e" TargetType="Text Block" 
BasedOn="{StaticResource commonTextStyle}"> 
〈Setter Property="TextWrappi ng" Val ue="Wrap" /> 
</Style> 


<Style x: Key="f rontMatterTextStyle" TargetType="Text Block" 
BasedOn="{Stati cResource commonTextStyle}"> 

〈Setter Property="TextAl ignment" Val ue="Center" /> 
</Style> 


<Style x:Key="imageStyle" TargetType=" Image"> 

<Setter Property=" Stretch" Val ue="None" /> 

〈Setter Property="Hori zontalA1ignment" Val ue="Center" /> 
</Style> 

</Page.Resources 〉 
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Notice the Margin value that provides a little spacing between the paragraphs. Each TextBlock 
element references either porographTextStyle (for the actual paragraphs of the book) or 
frontMatterTextStyle (for all the titles and other information that appears in the front of the book). 

I could have made the style for the Image element an implicit style by simply removing the x:Key 
attribute and removing the Style attributes from the Image elements. 

Many of the TextBlock elements that comprise the front matter have various local FontSize settings. 
Books generally are printed with black ink on white pages, so I hard-coded the Foreground of the 
TextBlock to black and set the Background of the Grid to white. To restrict the text to reasonable line 
lengths, the StockPonel is given a MoxWidth of 640 and centered within the ScrollViewer. Here’s a little 
excerpt of the alternating TextBlock elements and Image elements: 


Project: TheTaleOfTomKitten | File: MainPage.xaml (excerpt) 

〈Grid Background="Whi te"> 

〈Scroll Viewer> 

<StackPanel MaxWi dth="640" 

HorizontalA1i gnment="Center"> 

<!-- pg. 38 --> 

cTextBlock Styl e="{StaticResource paragraphTextStyl e}"> 

&#x2003;&#x2003;Mittens laughed so that she fell off the 
wall. Moppet and Tom descended after her; the pinafores 
and all the rest of Tom's clothes came off on the way down. 

</TextBlock> 


<TextBlock Styl e="{StaticResource paragraphTextStyl e}"> 

&#x2003;&#x2003;"Come! Mr. Drake Puddle-Duck," said Moppet 
- "Come and help us to dress him! Come and button up Tom!" 
</TextBlock> 


<Image Source="Images/tom39 .jpg" Style="{StaticResource imageStyle}" /> 
<!-- pg. 41 --> 

<TextBlock Styl e="{StaticResource paragraphTextStyl e}"> 

&#x2003;&#x2003;Mr. Drake Puddle-Duck advanced in a slow 
si deways manner, and pi eked up the various articles. 

</TextBlock> 

<Image Source="Images/tom40 .jpg" Styl e="{StaticResource imageStyle}" /> 


</StackPanel> 
</Scrol1 Viewer> 
</Grid> 


The two &#x200B; characters at the beginning of each paragraph are em-spaces. These provide 
a first-line indentation, which, unfortunately, is not provided by the TextBlock class. (This feature is 
provided by RichTextBlock, as you'll see in Chapter 16.) 
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You can read this book in either landscape or portrait mode: 


Mrs. Tabitha dressed Moppet and 
Mittens in clean pinafores and 
tuckers; and then she took all sorts of 
elegant uncomfortable clothes out of a 
chest of drawers, in order to dress up 
her son Thomas. 



Tom Kitten was very fat, and he 
had grown; several buttons burst off. 
His mother sewed them on again. 



Fancier StackPanel Items 


I mentioned earlier I’d be showing you a program that displays all 141 available Windows Runtime 
colors with the colors as well as their names and RGB values. My first example is called ColorListl, but 
let’s begin with the screen shot of the completed program so that you can see the goal: 
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This program contains a total of 283 StockPonel elements. Each of the 141 colors gets a pair: A 
vertical StackPonel is parent to the two Text Block elements, and a horizontal StockPanel is parent to a 
Rectangle and the vertical StockPonel. All the horizontal StockPanel elements are then children of the 
main vertical StackPonel in a ScrollViewer. The XAML file is responsible for centering that StockPonel: 

Project: ColorListl I File: MainPage.xaml (excerpt) 

<Grid Background=” {StaticResource ApplicationPageBackgroundThemeBrush}"> 

<Scrol1 Viewer> 

<StackPanel Name="stackPanel " 

HorizontalA1i gnment="Center" /> 

</Scrol1 Viewer> 

</Grid> 

Although the StockPanel is aligned in the center of the ScrollViewer (and is as wide as its widest child), 
the ScrollViewer occupies the entire width of the page. Any visible sliders or scrollbars appear on the 
far right of the page. Alternatively, you can put the Horizontal Alignment setting on the ScrollViewer, 
in which case the contents will still be the center but the ScrollViewer will be only as wide as the 
StackPonel. 

While enumerating through the static properties of the Colors class, the constructor in the 
code-behind file builds the nested StockPanel elements for each item: 

Project: ColorListl I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

public MainPage() 

{ 

this .InitializeComponent(); 

IEnumerable<PropertyInfo> properties = typeof (Colors) .GetTypelnfoC).DeclaredProperties; 


foreach (Propertylnfo property in properties) 

{ 

Col or clr = (Color)property.GetValue(null) ; 


StackPanel vertStackPanel = new StackPanel 

{ 

VerticalAlignment = VerticalAlignment .Center 

}； 


TextBlock txtblkName = new TextBlock 

{ 

Text = property.Name, 

FontSize = 24 

}； 

vertStackPanel.Children.Add(txtblkName); 


TextBlock txtblkRgb = new TextBlock 

{ 

Text = String. Format ("{0:X2}-{1:X2}-{2:X2}-{3:X2}" , 

cl r.A, clr.R, clr.G, clr.B), 

FontSize = 18 

}； 

vertStackPanel.Children.Add(txtblkRgb); 
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StackPanel horzStackPanel = new StackPanel 
{ 

Orientation = Orientation .Horizontal 

}； 

Rectangle rectangle = new Rectangle 
{ 

Width = 72, 

Height = 72, 

Fill = new SolidCol orBrush(cl r), 

Margin = new Thickness (6) 

}； 

horzStackPanel.Children.Add(rectangle); 
horzStackPanel.Children.Add(vertStackPanel); 
StackPanel.Chi Idren.Add(horzStackPanel); 



Now, there’s nothing really wrong with this code, except that there are numerous ways to do it 
better, and by "better 〃丨 don’t mean faster or more efficient but cleaner and more elegant and — most 
important — easier to maintain and modify. 

Let’s look at a better solution, but at the same time be aware that I won’t be finished with this 
example until Chapter 11, where you’ll see not only a better way of doing it, but the best way of doing it. 

Deriving from UserControl 

The key to making ColorListl better is expressing those color items — the nested StackPanel and 
TextBlock and Rectangle — in XAML. Just offhand, this doesn’t seem possible. We can’t put this XAML 
in the MainPage.xaml file because we can’t tell XAML to make 141 instances of the item unless we 
actually paste in 141 copies, and I suspect weYe all agreed that would be the worst way to do it. 

The ColorList2 program shows one common approach. After creating the ColorList2 project, I 
right-clicked the project name in the Solution Explorer and selected Add and New Item. In the Add 
New Item dialog box, I chose User Control and gave it a name of Colorltem.xaml. This process creates 
a pair of files: Colorltem.xaml accompanied by a code-behind file Colorltem.xaml.es. 

The Colorltem.xaml.es file created by Visual Studio defines a Colorltem class in the Co I or Lis t2 
namespace that derives from UserControl: 

namespace ColorList2 
{ 

public sealed partial cl ass Colorltem : UserControl 
{ 

public ColorltemO 
{ 

this. InitializeComponentO ; 

} 

} 

} 
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The Colorltem.xaml file created by Visual Studio says the same thing in XAML: 


<UserControl 

x:Cl ass="ColorLi st2.Colorltem" 

xml ns="http: //schemas.microsoft.com/winfx/2006/xaml/presentation" 
xml ns :x="http://schemas.microsoft.com/winfx/2006/xaml" 
xml ns : 1 ocal="usi ng : Col orLi st2" 

xml ns : d="http: //schemas.microsoft.com/expression/blend/2008" 

xml ns : mc="http : //schemas.openxmlformats.org/markup-compatibi1ity/2006" 

me: Ignorable="d" 

d : DesignHeight=" 300" 

d : DesignWi dth="400"> 


<Gri d> 


</Grid> 
</UserControl> 


You’ve actually already seen the UserControl class before because Page derives from UserControl. 
The "user" refers not to the end user of your application but to you, the programmer. Deriving from 
UserControl is the easiest way for you (the programmer) to make a custom control because you can 
define the visuals of the control in this XAML file. UserControl defines a property named Content, 
which is also the class’s content property, so anything you add within the UserControl tags is set to 
this Content property. 

Don’t worry about the d:DesignHeight and d:DesignWidth properties in the Colorltem.xaml file. 
Those are for Microsoft Expression Blend. The actual size of this control depends on its contents. 

The next step is to define the visuals of the color item in this Colorltem.xaml file: 


Project: ColorList2 I File: Colorltem.xaml (excerpt) 
<UserControl 

x:Class="ColorLi st2.Colorltem" … > 


<Grid> 

<StackPanel Orientati on="Hori zontal"> 
〈Rectangle Name=" rectangle" 
Width="72" 

Height= n 72__ 

Margin="6" /> 


<StackPane1 VerticalAli gnment="Center"> 


〈TextBlock Name="txtbl kName" 
FontSize="24" /> 

〈TextBlock Name="txtbl kRgb" 
FontSize="18" /> 


</StackPanel> 
</StackPanel> 
</Gri d> 

</UserControl > 
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It’s the same element hierarchy as defined in code in ColorListl, but now it’s actually readable. 
The Rectangle and the two TextBlock elements all have names, so they can be referenced in the 
code-behind file: 


Project: ColorList2 I File: Colorltem.xaml.es (excerpt) 


public sealed partial class Colorltem : UserControl 


public ColorItem(stri ng name, Color cl r) 
{ 

this .InitializeComponent(); 


rectangle.Fill = new SolidCol orBrush(cl r); 
txtblkName.Text = name; 

txtblkRgb.Text = String. Format ("{0:X2}-{1:X2}-{2 : X2}-{3:X2}" , 

clr.A, clr.R, clr.G, clr.B); 


} 

I’ve redefined the constructor to accept a color name and a Color value as arguments. It uses those 
arguments to set the appropriate properties of the Rectangle and two TextBlock elements. 


Let me warn you that defining a parameterized constructor in a UserControl derivative is extremely 
unorthodox. A much better approach is to define properties instead, but I don’t want to do that right 
now because these properties should really be dependency properties, and that’s too involved at the 
moment. 


Without a parameterless constructor, this Colorltem class cannot be instantiated in XAML. But 
that’s OK for this program because I’m not going to try instantiating it in XAML. The MainPage 
.xaml file for the ColorList2 project looks the same as the one for ColorListl. What’s different is the 
simplicity of the code-behind file: 


Project: ColorList2 | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 
{ 

public MainPageC) 

{ 

this .InitializeComponent(); 

IEnumerable<PropertyInfo> properties = typeof (Colors) .GetTypelnfoC).DeclaredProperties; 

foreach (Propertylnfo property in properties) 

{ 

Color clr = (Color)property.GetValue(null); 

Colorltem clrltem = new Colorltem (property.Name, clr); 
stackPanel.Children.Add(clrltem); 



Each Colorltem is instantiated with a name and Color and then added to the StackPanel. 
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Creating Windows Runtime Libraries 


Let’s create another version of this program, but this time the Colorltem class will be in a library that 
can be shared with other projects. 


You can create a Visual Studio solution containing only a library project, but it’s more common to 
add a library project to the solution of an existing application project. As you’re developing the code 
in the library, you want to test it, and it really helps to have an application project in the same solution 
for that purpose. After developing a library in conjunction with an application, you can then share 
that library later if desired. 


So let’s create a new application project named ColorList3. In the Solution Explorer, add a library 
project to the solution by right-clicking the solution name and selecting Add and New Project. (Or 
pick Add New Project from the File menu.) In the Add New Project dialog box, at the left select Visual 
C# and the option for creating a new Windows 8 project. From the list of templates, select Class 
Library. 


Generally, a library has a multilevel name separated by periods. This name also becomes the 
default namespace for that project. The library name usually begins with a company name (or its 
equivalent), so for this example I wanted to choose a library name of Petzold.Windows8.Controls. 
However, I had problems with a multileveled assembly name, so I left out the periods and used 
PetzoldWindow8Controls instead, and then later I changed the namespace to Petzold.Windows8 
.Controls. 

In a new library, Visual Studio automatically creates a file named Classl.cs, but you can delete that. 
Now right-click the library project name and select Add and New Item, and in the Add New Item 
dialog box, select User Control and give it a name of Colorltem. I decided to enhance the visuals of 
this Colorltem a little beyond the one you’ve already seen: 


Solution: ColorList3 I Project: PetzoldWindows8Controls | File: Colorltem.xaml (excerpt) 

<UserControl … > 

<Gri d> 

<Border BorderBrush="{Stati cResource ApplicationForegroundThemeBrush}" 
BorderThickness="l" 

Width="336" 

Margin="6"> 

<StackPanel Orientati on="Hori zontal"> 

〈Rectangle Name=" rectangle" 

Width="72” 

Height="72" 

Margin="6" /> 

<StackPanel VerticalAli gnment="Center"> 

<TextBlock Name="txtbl kName" 

FontSize="24" /> 

<TextBlock Name="txtbl kRgb" 

FontSize="18" /> 


</StackPanel > 
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</StackPanel> 

</Border> 

</Grid> 

</UserControl > 


Notice that I’ve given it a Border with an explicit Width property and a Margin. I chose this width 
empirically based on the longest color name (LightGoldenrodYellow). Notice also that the BorderBrush 
is set to a predefined identifier, which will be black with a light theme and white with a dark theme. 
Themes are set on applications rather than libraries — indeed, a library has no App class to set a 
theme — so this brush will be based on the theme of the application that uses Colorltem. 

We still haven’t touched the ColorList3 application project. Despite the fact that they’re in 
the same solution, this application project will need a reference to the library, so right-click the 
References item under the ColorList3 project and select Add Reference. In the Reference Manager 
dialog box, at the left select Solution (indicating you want an assembly in the same solution), click 
PetzoldWindows8Controls, and click OK. 

There is a distinct advantage to having both these projects in the same solution: Whenever you 
build ColorList3, Visual Studio will also rebuild the PetzoldWindows8Controls library if it’s not up to 
date. 

The MainPage.xaml file in ColorList3 is the same as in the previous two projects. The code-behind 
file needs a using directive for the namespace of the library, but otherwise it’s the same as ColorList2: 


Project: ColorList3 | File: MainPage.xaml.es 

using System.Col 1ections.Generic; 

using System.Reflection; 

using Windows.UI; 

using Windows.UI.Xaml .Controls; 

using Petzold.Windows8.Controls; 


namespace ColorList3 
{ 

public sealed partial cl ass MainPage : Page 
{ 

public MainPage() 

{ 

this. InitializeComponentC); 

IEnumerable<PropertyInfo> properties = 

typeof (Colors) .GetTypelnfoC).DeclaredProperties; 

foreach (Propertylnfo property in properties) 

{ 

Color clr = (Color)property.GetVal ue(nul 1); 

Colorltem clrltem = new Colorltem (property.Name, clr); 
stackPanel.Children.Add(clrltem); 
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Here’s the result: 




LightBlue 

FF-AD-D8-E6 

■ 

LightCoral 

FF-F0-80-80 

LightCyan 

FF-EO-FF-FF 

LightGoldenrodYellow 

FF-FA-FA-D2 


LightGray 

FF-D3-D3-D3 

■ 

LightGreen 

FF-90-EE-90 


LightPink 

FF-FF-B6-C1 

■ 

LiahtSalmon 


When creating the Petzold.Windows8.Controls library, I indicated that you should choose Class 
Library from the Add New Project dialog box. There is another option for creating a library labeled 
Windows Runtime Component. For this particular example, it doesn’t matter which one you choose. 

In fact, you can right-click the library project name, select Properties, and in the Application screen 
change the Output type from Class Library to Windows Runtime Component. The ColorList3 program 
will run the same. 

The big difference is this: The library you create by selecting Class Library can be accessed only 
from other C# and Visual Basic applications. A Windows Runtime Component can additionally be ac¬ 
cessed from C++ and JavaScript. It is the Windows Runtime Component that allows language interop¬ 
erability for Windows 8 applications. 

Consequently, a Windows Runtime Component has some restrictions that a regular Class Library 
does not Public classes must be sealed, for example. If you remove the sealed keyword from the 
definition of the Colorltem control, that class cannot be part of a Windows Runtime Component. The 
other major rules involve structures — you can’t have any public members that are not fields — and the 
restriction of data types passing over the API to Windows Runtime types. 

The C++ version of StackPanelWithScrolling includes a Windows Runtime Component named 
ReflectionHelper written in C# that simplifies the use of reflection by the C++ programs. Chapter 15, 
"Going Native," shows the opposite approach: a Windows Runtime Component written in C++ that 
gives C# programs access to DirectX classes. 
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The Wrap Alternative 


Now let’s use that PetzoldWindows8Controls library in another project. There are three ways to do it: 

Method 1: Add a new application project to the same solution as the existing library: the ColorList3 
solution, in this example. This is the easiest approach, and it certainly makes sense if the two 
applications are related some way. 

Instead, I’m going to use one of the other two methods. These two methods both involve creating 
a new solution and application project, which I’ll call ColorWrap. This project needs a reference to the 
PetzoldWindows8Controls library. 

Method 2: Right-click the References item in the ColorWrap project, and select Add Reference. 

In the left column of the Reference Manager, select Browse, and then click the Browse but¬ 
ton in the lower-right corner. This will allow you to browse to the directory location where 
the PetzoldWindows8Controls.dll file is located (which is the bin/Debug directory of the 
PetzoldWindows8Controls project in the ColorList3 solution), and you can select that DLL. 


The disadvantage to this method is that you’re assuming that the library is complete and finished 
and that you won’t need to make any changes. You’re referencing a DLL rather than the project 
with its source code. However, in my experience the really big disadvantage to this method is that it 
doesn’t work quite right with the current release of Windows 8 when there are XAML files involved. 

That leaves us with: 

Method 3: In the ColorWrap solution, right-click the solution name and select Add and Existing 
Project. The existing project you want to add is the library. In the Add Existing Project dialog box, 
navigate to the PetzoldWindows8Controls.csproj file. This is the C# project file maintained by Visual 
Studio in the ColorList3 solution. Select that. The library project is not copied! Instead, only a refer¬ 
ence is created to that library project. Regardless, Visual Studio can still determine if the library needs 
to be rebuilt, and it performs that rebuild if necessary. 


Now the PetzoldWindows8Controls project is part of the ColorWrap solution, but the ColorWrap 
application project still needs a reference to the library. Right-click the References section under the 
ColorWrap project and select the library from the solution, just as you did in ColorList3. 

It could be that you have two instances of Visual Studio running, perhaps with the ColorList3 and 
ColorWrap solutions loaded, both of which let you make changes to the PetzoldWindows8Controls 
library. That’s generally OK as long as you save or compile after making changes. If the same file is 
open in both instances of Visual Studio and you make changes to that file, the other instance of Visual 
Studio will notify you of changes when that file is saved to disk. 

With those preliminaries out of the way, let’s focus on the ColorWrap program, which demonstrates 
how to display these colors with a VariobleSizedWropGrid panel. Despite the name of this panel, it really 
wants all the items to be the same size. That’s why I added the explicit Width to the Border in Colorltem. 

Like StackPanel, VariobleSizedWropGrid has an Orientation property and the default is 
Vertical. The first items in the Children collection are displayed in a column. The difference is that 


130 PART Elementals 



VariobleSizedWropGrid will use multiple columns, just like the Windows 8 start screen. This means that 
the default VariobleSizedWropGrid must be horizontally scrolled, so ScrollViewer properties must be 
set accordingly. Here’s the XAML file: 


Project: ColorWrap | File: MainPage.xaml (excerpt) 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<ScrollViewer HorizontalScrollBarVisibi1i ty="Vi sible" 

Vertical ScrollBarVisibi1i ty="Di sabled"> 

<VariableSizedWrapGrid Name="wrapPanel " /> 

</ScrollViewer> 

</Grid> 


The code-behind file is similar to the previous program except that now it puts the items into 
wrap Pan el: 


Project: ColorWrap I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

public MainPageO 

{ 

this. Ini ti alizeComponent(); 

IEnumerable<PropertyInfo> properties = typeof (Colors) .GetTypelnfoO.DeclaredProperties; 

foreach (Propertylnfo property in properties) 

{ 

Color clr = (Color)property .GetValue(null) ; 

Colorltem clrltem = new Colorltem (property.Name, clr); 
wrapPanel.Children.Add(cl rltem); 

} 

} 

} 

And here it is: 




DarkSlateGray 

FF-2F-4F-4F 

Firebrick 

FF-B2-22-22 

DarkTurquoise 

FF-00-CE-D1 

■ 

FloralWhite 

FF-FF-FA-FO 

DarkViolet 

FF-94-00-D3 

■ 

ForestGreen 

FF-22-8B-22 






Scrolling is horizontal. 
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The Canvas and Attached Properties 


The final Panel derivative I’ll discuss in this chapter is the Canvas. In one sense, Convos is the most 
"traditional” type of panel because it allows you to position elements at precise pixel locations. 

But what property of the child element do you set to indicate the element’s position relative to the 
Canvas? If you’ve scoured the properties defined by UlElement and FromeworkElement searching for 
something named Location or Position or X or Y, you haven’t found it. Properties that let you specify 
coordinate positions exist for drawing vector graphics but not for other elements. Such a property 
doesn’t make much sense in the Windows Runtime because it is not applicable when you're using a 
Grid, a StockPanel, or a WropPanel. We’ve managed to make it this far without specifying pixel loca¬ 
tions for positioning elements, and the only time one is needed is when the element is a child of a 
Convos. 

For that reason, Canvas itself defines the properties used to position elements relative to itself. 
These are a very special type of property known as attached properties, and they are a subset of de¬ 
pendency properties. Attached properties defined by one class {Convos, in this example) are actually 
set on instances of other classes (children of the Canvas, in this case). The objects on which you set an 
attached property don’t need to know what that property does or where it came from. 

Let’s see how this works. The TextOnCanvas project has a XAML file that contains a Convos within 
the standard Grid. (You can alternatively replace the Grid with the Canvas.) The Convos contains three 
TextBlock children: 


Project: TextOnCanvas I File: MainPage.xaml (excerpt) 

<Page 

x:Cl ass="TextOnCanvas. MainPage" 

FontSi ze="48"> 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Canvas> 

〈TextBlock Text="Text on Canvas at (0, 0)" 

Canvas _ Left="0" 

Canvas .Top="0" /> 

〈TextBlock Text="Text on Canvas at (200, 100)" 

Canvas _ Left="200" 

Canvas .Top="100" /> 

〈TextBlock Text="Text on Canvas at (400, 200)" 

Canvas _ Left="400" 

Canvas .Top="200" /> 

</Canvas> 

</Gri d> 

</Page> 
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Here’s the (rather unexciting) result: 

Text on Canvas at (0, 0) 

Text on Canvas at (200, 100) 

Text on Canvas at (400, 200) 


Look at that markup again, and take special note of the strange syntax: 

〈TextBlock Text="Text on Canvas at (200, 100)" 

Canvas. Left="200" 

Canvas .Top="100" /> 

Judging from their names, the Canvas.Left and Convas.Top attributes appear to be defined by 
the Canvas class, and yet they are set on the children of the Canvas to indicate their positions. 

XAML attribute names identified with both class and property names like this are always attached 
properties. 

The funny thing is, Canvas actually doesn’t define any properties named Left and Top\ It defines 
properties and methods with similar names but not those names exactly. 

The nature of these attached properties might become a little clearer by examining how they are 
set in code. The XAML file for the TapAndShowPoint program contains only a named Canvas in the 
standard Grid: 

Project: TapAndShowPoint | File: MainPage.xaml (excerpt) 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

<Canvas Name="canvas" /> 

</Grid> 

Everything else is the responsibility of the code-behind file. It overrides the OnTapped method to 
create a dot (an Ellipse element actually) and a TextBlock, both of which it adds to the Canvas at the 
point where the screen was tapped: 

Project: TapAndShowPoint | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 


public MainPage() 
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} 


this .InitializeComponent(); 


protected override void OnTappedCTappedRoutedEventArgs args) 

{ 

Point pt = args.GetPosi tion(this) ; 

// Create dot 

Ellipse ellipse = new Ellipse 

{ 

Width = 3, 

Height = 3 ， 

Fill = this .Foreground 

}； 

Canvas .SetLeft(el1ipse, pt.X); 

Canvas .SetTopCel1ipse, pt.Y); 
canvas.Children.Add(ell ipse); 

// Create text 

TextBlock txtblk = new TextBlock 

{ 

Text = String . Format (" ({0})" , pt) ， 

FontSize = 24 ， 

}； 

Canvas .SetLeft(txtblk, pt.X); 

Canvas .SetTopCtxtblk, pt.Y); 
canvas.Children.Add(txtblk); 

args.Handled = true ; 
base.OnTapped(args); 



As you tap the screen, the dots and text appear at the tap points: 



( 544 , 98 ) 


( 194 , 122 ) 

( 299 , 147 ) 

( 642 , 176 ) 

( 1058 , 127 ) 

( 268 , 266 ) 

( 409 , 293 ) 


' ( 888 - 24 °>( 983 , 257 ) 

( 200 , 351 ) 

( 700 , 365 ) 


( 362 , 465 ) 

•(H) 

( 1123 , 443 ) 

( 954 , 508 ) 

( 265 , 651 ) 

( 554 , 585 ) 

( 888 , 603 ) 
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Here’s how the position of the dot is specified in code as it’s added to the Children collection of the 
Canvas: 

Canvas .SetLeft(el1ipse, pt.X); 

Canvas .SetTop(el1ipse, pt.Y); 
canvas.Children.Add(ell ipse); 

The order doesn’t matter: You could add the element to the Canvas first, and then set its position. 

The Convos.SetLeft and Canvas.SetTop static methods play the same role here as the Canvas.Left and 
Canvas .Top attributes in XAML. They let you specify a coordinate point where a particular element 
is to be positioned. (However, there’s a little flaw in the approach I’ve used to position the dots. This 
flaw becomes evident if you make the Ellipse a little larger. The program should really be putting the 
center of the dot at the tapped point, and instead the Canvas .Set Left and Canvas.SetTop calls I’ve 
used position the upper-left corner of the Ellipse there. If you want the center of the Ellipse at the 
point pt, you’ll want to subtract half its width from pt.X and half its height from pt.Y) 

I mentioned that Canvas doesn’t define Left and Top properties specifically. Instead, Canvas defines 
static Set Left and SetTop methods as well as static properties of type DependencyProperty. Here’s how 
the two DependencyProperty objects might be defined if the Canvas class were written in C#: 

public static DependencyProperty LeftProperty { get; } 
public static DependencyProperty TopProperty { get; } 

As you’ll see in a later chapter, these are special types of dependency properties in that they can be 
set on elements other than Canvas. 

Let me show you something interesting. The TapAndShowPoint program calls the static 
Convos.SetLeft and Canvas.SetTop methods like this: 

Canvas .SetLeft(el1ipse, pt.X); 

Canvas .SetTop(el1ipse, pt.Y); 

An alternative approach — just as legal, just as valid, and 100 percent equivalent — involves calling Set- 
Value on the child element and referencing the static DependencyProperty objects defined by Canvas: 

el 1ipse.SetValue (Canvas .LeftProperty, pt.X); 
el 1ipse.SetVal ue(Canvas .TopProperty, pt.Y); 

These statements are exactly equivalent to the Convos.SetLeft and Canvas.SetTop calls, and it doesn’t 
matter which form you use. 

You’ve seen that SetVolue method before. SetValue is defined by DependencyObject and inherited 
by very many classes in the Windows Runtime. A property like Font Size is actually defined in terms of 
the static dependency property that becomes an argument to this same SetVolue method: 

public double FontSize 
{ 

set { SetValue(FontSizeProperty, value); } 

get { return (double)GetVal ue(FontSizeProperty); } 
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In fact, although I have never seen the internal source code of the Canvas class, I can practically 
guarantee you that the Set Left and SetTop static methods in Canvas are defined with code that’s 
equivalent to this C# syntax: 

public static void SetLeft(DependencyObject element, double value) 

{ 

element.SetValue(LeftProperty, value); 

} 

public static void SetTopCDependencyObject element, double value) 

{ 

element.SetValue(TopProperty, value); 

} 

These methods show very clearly how the dependency property is actually being set on the child 
element rather than the Canvas. 

Canvas also defines Get Left and GetTop methods, defined in code equivalent to this: 

public static double GetLeft(DependencyObject element) 

{ 

return (doubl e) element.GetValue(LeftProperty); 

} 

public static double GetTop (DependencyObject element) 

{ 

return (doubl e) element.GetValue(TopProperty); 

} 

The Canvas class uses these methods internally to obtain the left and top settings on each of its 
children so that it can position them during the layout process. 

The static Set Left, SetTop, Get Left, and GetTop methods suggest that the dependency property 
system involves a dictionary of sorts. The SetVal ue method allows an attached property like Convos 
.LeftProperty to be stored in an element that has no knowledge of this property or its purpose. Can¬ 
vas can later retrieve this property to determine where the child should appear relative to itself. 


The Z-Index 


Convos has a third attached property that you can set in XAML with the attribute Canvas.Zlndex. The 
"Z" in Zlndex refers to a three-dimensional coordinate system, where the Z axis extends out of the 
screen toward the user. 

When sibling elements overlap, they are normally displayed in the order they appear in the visual 
tree, which means that elements early in a panel’s Children collection can be covered by elements 
later in the Children collection. For example, consider the following: 

<Gri d> 

〈TextBlock Text="Bl ue Text" Foreground="Bl ue" FontSi ze="96" /> 

<TextBlock Text="Red Text" Foreground="Red" FontSi ze="96" /> 

</Grid> 


136 PART Elementals 



The red text obscures part of the blue text. 

You can override that behavior with the Canvas.Zlndex attached property, and the weird thing is 
this: It works with all panels, and not just Canvas. To make the blue text appear on top of the red text, 
give it a higher z-index: 

<Grid> 

<TextBlock Text="Bl ue Text" Foreground="Bl ue" FontSi ze="96" Canvas .ZIndex="l" /> 

<TextBlock Text="Red Text" Foreground="Red" FontSi ze="96" Canvas .Zlndex="0" /> 

</Grid> 


Canvas Weirdness 


Much of what IVe described about layout earlier in this chapter doesn’t apply to the Canvas. Layout 
within a Canvas is always child-driven. The Canvas always offers its children an infinite size, which 
means that each child sets a natural size for itself and that’s the only space the child occupies. 

Horizon to I A lignmen t and VerticolAlignment settings have no effect on a child of a Canvas. Likewise, 
the Stretch property of Image has no effect when the Image is a child of a Canvas: Image always 
displays the bitmap in its pixel size. Rectangle and Ellipse shrink to nothing in a Canvas unless given an 
explicit width and height. 

Although Horizontal Alignment and VerticolAlignment have no effect on a child of the Canvas, 
they do have an effect when set on the Canvas itself. With other panels, when you set the alignment 
properties to something other than Stretch, the panel becomes as small as possible while still encom¬ 
passing its children. The Canvas, however, is different. Set HorizontolAlignment and VerticolAlignment 
to values other than Stretch, and the Canvas shrinks to nothing regardless of its children. 

Even when the Canvas shrinks down to a zero size, the display of its children is not affected. 
Conceptually, the Canvas is more like a reference point than a container, and the size of the children 
of a Canvas are ignored in layout. 

You can use this characteristic of the Canvas to your advantage. For example, suppose you try to 
display a TextBlock in a Grid that is obviously too small for it: 

〈Grid Width= n 200" Hei ght="100"> 

〈TextBlock Text="Text in a Small Grid" FontSi ze="144" /> 

</Grid> 

The TextBlock is clipped to the dimensions of the Grid. You could make the Grid larger of course, but 
you might be stuck with this Grid size, perhaps because of other child elements. Still, you want the 
TextBlock to be aligned with these other elements without being clipped to the Grid. 
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The extremely simple solution is to put a Canvas in the Grid and put the TextBlock in that Canvas: 


〈Grid Width="200" Hei ght="100"> 

<Canvas> 

〈TextBlock Text="Text in a Small Grid" FontSize="144" /> 
</Canvas> 

</Grid> 


Even though the Canvas is now clipped to the size of the Grid, the TextBlock is not. The TextBlock is 
still where you want it — aligned with the upper-left corner of the Grid — but it’s now displayed without 
any clipping. The TextBlock essentially exists outside of normal layout. 

It’s a very simple technique that can be very useful when you need it. 
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CHAPTER 5 

Control Interaction 


E arly on in this book I made a distinction between classes that derive from FrameworkElement 
and those that derive from Control. I’ve tended to refer to FrameworkElement derivatives (such 
as TextBlock and Image) as "elements" to preserve this distinction, but a deeper explication is now 
required. 

The title of this chapter might suggest that elements are for presentation and controls are for 
interaction, but that’s not necessarily so. It is the UlElement class that defines all the user-input events 
for touch, mouse, stylus, and keyboard, which means that elements as well as controls can interact 
with the user in very sophisticated ways. 

Nor are elements deficient in layout, styling, or data binding capabilities. It’s the 
FrameworkElement class that defines layout properties such as Width, Height, Horizontal Alignment, 
Vertical A lign m en t, and Margin, as well as the Style property and the SetBinding method. 


The Control Difference 


Visually and functionally, FrameworkElement derivatives are primitives — atoms, so to speak — while 
Control derivatives are assemblages of these primitives, or molecules in this analogy. A Button is 
actually constructed from a Border and a TextBlock (in many cases). A Slider consists of a couple of 
Rectangle elements with a Thumb, which itself is a Control probably built from a Rectangle. Anything 
that has visual content beyond text, a bitmap, or vector graphics is almost certainly a Control 
derivative. 

Consequently, one of the most important properties defined by Control is called Template. As 111 
demonstrate in Chapter 11, "The Three Templates,” this property allows you to completely redefine 
the appearance of a control by defining a visual tree of your own invention. It makes sense to visually 
redefine a Button because (for example) you might want it to be round rather than rectangular 
because you want to put it on an application bar. It makes no sense to visually redefine a TextBlock or 
Image because there’s nothing you can do with it beyond the text or bitmap itself. If you want to add 
something to a TextBlock or Image, you’re defining a Control because you’re constructing a visual tree 
that includes the element primitive. 
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Although you can derive a custom class from FrameworkElement, there is little you can do with the 
result. You can’t give it any visuals. But when you derive from Control, you generally give your custom 
control a default visual appearance by defining a visual tree in XAML. 

Control defines a bunch of properties that the Control class itself does not need. These are for 
use by classes that derive from Control, and consist of properties mostly associated with TextBlock 
[CharacterSpacing, FontFamily, Font Size, FontStretch, FontStyle, FontWeight, and Foreground) and 
Border {Background, BorderBrush, BorderThickness, and Podding). Not every Control derivative has text 
or a border, but if you need those properties when creating a new control or creating a new template 
for an existing control, they are conveniently provided. Control also provides two new properties 
named HorizontalContentAlignment and VerticalContentAlignment for purposes of defining control 
visuals. 

A Control derivative often defines some new properties and events. Commonly, a Control 
derivative will process user-input events from the pointer, mouse, stylus, and keyboard and will 
convert that input into a higher-level event. For example, the ButtonBase class (from which all the 
buttons derive) defines a Click event. The Slider defines a ValueChonged event indicating when its 
Value property changes. The TextBox defines a TextChonged event indicating when its Text property 
changes. 

It turns out that in real life, Control derivatives really do interact more with users, so the title of this 
chapter is accurate. For the convenience of working with user input, Control provides protected virtual 
methods corresponding to all the user-input events defined by UlElement. For example, UlElement 
defines the Topped event, but Control defines the protected virtual method OnTapped. Control also 
defines an IsEnabled property so that controls can avoid user input if input is not currently applicable, 
and it defines an IsEnobledChanged event that is fired when the property changes. This is the only 
public event actually defined by Control. 

The idea of a control having "input focus” is still applicable in Windows 8. When a control has the 
input focus, the user expects that particular control to get most keyboard events. (Of course, some 
keyboard events, such as the Windows key, transcend input focus.) For this purpose, Control defines a 
Focus method, as well as OnGotFocus and OnLostFocus virtual methods. 

In connection with keyboard focus is the idea of being able to navigate among controls by using 
the keyboard Tab key. Control provides for this by defining IsTabStop, Tab Index, and TabNavigation 
properties. 

Many Control derivatives are in the Windows.Ul.Xaml.Controls namespace, but a few are in 
the Windows.Ul.Xoml.Controls.Primitives namespace. The latter namespace is generally reserved 
for those controls that usually appear only as parts of other controls, but that’s a suggestion rather 
than a restriction. 
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Most Control derivatives derive directly from Control, but four important classes derive from 
Control to define their own subcategories of controls. Here they are: 

Object 

DependencyObject 

UlElement 

FromeworkElement 

Control 

ContentCoritrol 
ItemsControl 
RangeBase 
User Control 

ContentCoritrol — from which important classes like Button, ScrollViewer, and AppBar derive — 
seemingly does little more than define a property named Content of type object. For a Button, for 
example, this Content property is what you set to whatever you want to appear inside the Button. 

Most often this is text or a bitmap, but you can also use a panel that contains other content. 

It is interesting that the Content property of ContentCoritrol is of type object rather than UlElement. 
There’s a good reason for that. You can actually put pretty much any type of object you want as the 
content of a Button, and you can supply a template (in the form of a visual tree) that tells the Button 
how to display this content. This feature is not so much used for Button, but it’s used a great deal for 
items in ItemsControl derivatives. I’ll show you how to define a content template in Chapter 11. 

ItemsControl is the parent class to a bunch of controls that display collections of items. Here you’ll 
find the familiar List Box and ComboBox as well as the new Windows 8 controls FlipView, GridView, and 
ListView. Again, Chapter 11. 

There are a couple ways to create custom controls. The really simple way is by defining a Style for 
the control, but more extensive visual changes require a template. In some cases you can derive from 
an existing control to add some features to it, or you can derive from ContentCoritrol or ItemsControl 
if these controls provide features you need. 

But one of the most common ways to create a custom control is by deriving from UserControl. This 
is not the approach you'll use if you want to market a custom control library, but it’s great for controls 
that you use yourself within the context of an application. 

The Slider for Ranges 

In the Control class hierarchy shown above, the remaining important class is RangeBase, which has 
three derivatives: ProgressBar, ScrollBor, and Slider. 

Which of these is not like the others? Obviously ProgressBor, which exists in this hierarchy mainly 
to inherit several properties from RangeBase: Minimum, Maximum, SmollChonge, LorgeChonge, and 
Value. In every RangeBase control, the Value property takes on values of type double ranging from 
Minimum through Maximum. With the ScrollBar and Slider, the Value property changes when the user 
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manipulates the control; with ProgressBar, the Value property is set programmatically to indicate the 
progress of a lengthy operation. 

ProgressBar has an indeterminate mode to display a row of dots that skirt across the screen, but 
also available is ProgressRing, which displays a now familiar spinning circle of dots. 

In the quarter-century evolution of Windows, the ScrollBar has slipped from its high perch in the 
control hierarchy and is commonly seen today only in a ScrollViewer control. Try to instantiate the 
Windows Runtime version of ScrollBar, and you won't even see it. If you want to use ScrollBar, you'll 
have to supply a template for it. Like RongeBase, ScrollBar \s defined in the Windows.Ul.Xoml.Controls 
.Primitives namespace, indicating that it’s not something application programmers normally use. 

For virtually all needs that involve choosing from a range of values, ScrollBar has been replaced 
with Slider, and with touch interfaces, Slider has become simpler than ever. In its default manifestation, 
Slider has no arrows. It simply jumps to the value corresponding to the point where you touch the 
Slider or drag your finger or mouse. 

The Value property of the Slider can change either programmatically or through user 
manipulation. To obtain a notification when the Value property changes, attach an event handler for 
the VolueChanged event, such as shown in the SliderEvents project: 


Project: SliderEvents I File: MainPage.xaml (excerpt) 

<Grid Background:'' {StaticResource ApplicationPageBackgroundThemeBrush}"> 

<StackPanel> 

〈Slider Val ueChanged="OnSl iderValueChanged" /> 

<TextBlock HorizontalAli gnment="Center" 

FontSize="48" /> 

〈Slider Val ueChanged="OnSl iderValueChanged" /> 

<TextBlock HorizontalAli gnment="Center" 

FontSize="48" /> 

</StackPanel> 

</Grid> 

Both Slider controls here share the same event handler. The idea behind this simple program is 
that the current Value of each Slider is displayed by the TextBlock below it. This might be considered 
somewhat challenging when you notice that nothing in this XAML file is assigned a name. However, 
the event handler makes a few assumptions. It assumes that the parent to the Slider is a Panel, and the 
next child in this Panel is a TextBlock: 

Project: SliderEvents I File: MainPage.xaml.es (excerpt) 

void OnSliderVal ueChanged(object sender, RangeBaseValueChangedEventArgs args) 

{ 

Slider slider = sender as Slider; 

Panel parentPanel = siider.Parent as Panel ; 

int childlndex = parentPanel.Children.IndexOf(slider); 

TextBlock txtblk = parentPanel.Children[childlndex + 1] as TextBlock; 
txtblk.Text = args.NewValue.ToString(); 

} 
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This little bit of "trickery” merely demonstrates that there’s more than one way to access elements 
in the visual tree. In the final step, the Text property of the Text Block is assigned the NewVolue 
argument from the event arguments, converted to a string. Equally valid would be using the Value 
property of the Slider: 

txtblk.Text = siider.Value.ToString(); 

Although RongeBoseVolueChongedEventArgs derives from Routed Event, this is not a routed 
event. The event does not travel up the visual tree. The sender argument is always the Slider, and the 
OriginalSource property of the event arguments is always null. 

When you run the program, you’ll notice that the TextBlock elements initially display nothing. The 
ValueChanged event is not fired until Value actually changes from its default value of zero. 

As you touch a Slider or click it with a mouse, the value jumps to that position. You can then 
sweep your finger or mouse pointer back and forth to change the value. As you manipulate the Slider 
controls, you’ll see that they let you select values from 0 to 100, inclusive: 



This default range is a result of the default values of the Minimum and Maximum properties, which 
are 0 and 100, respectively. Although the Value property is a double, it takes on integral values as a 
result of the default StepFrequency property, which is 1. 


By default the Slider is oriented horizontally, but you can switch to vertical with the Orientation 
property. The thickness of the Slider cannot be changed except by redefining the visuals with a 
template. The total thickness of the control in layout includes a bit more space than the visuals imply. 
In layout, the default height of a horizontal Slider is 60 pixels; the default width of a vertical Slider is 45 
pixels. In use, these dimensions are adequate for touch purposes. 
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If you press the Tab key while this program is running, you can change the keyboard input focus 
from one Slider to another and then use the keyboard arrow keys to make the value go up or down. 
Pressing Home and End shoots to the minimum and maximum values. 

Some other variations are illustrated in the next project called SliderBindings, in which IVe moved 
all the updating logic to the XAML file. Three Slider controls are instantiated in a Stack Pan el and 
alternated with TextBlock elements with bindings to the Value properties of each Slider. An implicit 
style for the TextBlock is defined to reduce repetitive markup: 


Project: SliderBindings | File: MainPage.xaml (excerpt) 

<Crid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Grid.Resources 〉 

〈Style TargetType="TextBlock"> 

〈Setter Property="FontSi ze" Value="48" /> 

〈Setter Property="Hori zontalA1ignment" Val ue="Center" /> 
</Style> 

</Grid.Resources 〉 


<StackPanel> 

〈Slider Name="sl iderl" /> 

〈TextBlock Text="{Binding ElementName=sl iderl, Path=Value}" /> 

〈Slider Name="sl ider2" 

IsDirecti onReversed="True" 

StepFrequency="0.01" /> 

<TextBlock Text="{Binding ElementName=sl ider2, Path=Value}" /> 

〈Slider Name="sl ider3" 

Mi nimum="-l" 

Maximum="l M 
StepFrequency="0 .01" 

Smal1 Change:" 0•01" 

LargeChange="0. 1" /> 

〈TextBlock Text="{Binding ElementName=sl ider3, Path=Value}" /> 
</StackPanel> 

</Grid> 
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Bindings obtain initial values and don’t wait for the first ValueChonged event to be fired. The 
bindings then keep track of changing values resulting from user manipulation: 


22 

19.04 

- 0.18 

The markup for the second Slider sets the StepFrequency property to 0.01 and also sets 
IsDirect ion Reversed to true so that the minimum value of 0 occurs when the thumb is positioned to 
the far right. It’s rather rare to set IsDirectionReversed to true for horizontal sliders but more common 
for vertical sliders. The default vertical slider has a minimum value when the slider is all the way down, 
and for some purposes that should be a maximum value. 

For that second Slider, however, the keyboard arrow keys change the value in increments of 1 rath¬ 
er than the StepFrequency of 0.01. The keyboard interface is governed by the SmallChange property, 
which by default is 1. 

The third Slider has a range from -1 to 1. When the Slider is first displayed, the thumb is set 
in the center at the default Value of 0. I’ve set both StepFrequency and SmallChange to 0.01, and 
LorgeChange to 0.1, but I’ve found no way to trigger the LorgeChange jump with either the mouse or 
keyboard. 

The Slider class defines TickFrequency and TickPlocement properties to display tick marks 
adjacent to the Slider. If the Background and Foreground properties of the Slider are set, the Slider 
uses Foreground for the slider area associated with the minimum value and Background for the 
area associated with the maximum value, but it switches to default colors when the Slider is being 
manipulated or when the mouse hovers overhead. 

As we begin creating more Slider controls, it becomes necessary to find a better way to lay them 
out on the page. It’s time to get familiar with the Grid. 
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The Grid 


The Grid probably seems like a familiar friend at this point because it’s been in almost every program 
in this book, but obviously we haven’t gotten to know it in any depth. Many of the programs in the 
remainder of this book will use the Grid not in its single-cell mode but with actual rows and columns. 

The Grid has a superficial resemblance to the HTML table, but it’s quite different. The Grid doesn’t 
have any facility to define borders or margins for individual cells. It is strictly for layout purposes. Any 
sprucing up for presentation must occur on the parent or children elements: You can put the Grid in a 
Border, and Border elements can adorn the contents of the individual Grid cells. 


The number of rows and columns in a Grid must be explicitly specified; the Grid cannot determine 
this information by the number of children. Children of the Grid generally go in a particular cell, which 
is an intersection of a row and column, but children can also span multiple rows and columns. 


Although the numbers of rows and columns can be changed programmatically at run time, it’s 
not often done. Much more common is to fix the number of desired rows and columns in the XAML 
file. This is accomplished with objects of type RowDefinition and ColumnDefinition added to two 
collections defined by Grid called RowDefinitions and ColumnDefinitions. 

The size of each row and column can be defined in one of three ways: 

■ An explicit row height or column width in pixels 

■ Auto, meaning based on the size of the children 

■ Asterisk (or star), which allocates remaining space proportionally 

In XAML, property-element syntax is used to fill the RowDefinitions and ColumnDefinitions 
collections, so a typical Grid looks like this: 

<Gri d> 

<Grid.RowDefinitions> 

〈RowDefinition Height="Auto" /> 

〈RowDefinition Height="55" /> 

〈RowDefinition Height="*" /> 

</Grid.RowDefinitions> 

<Grid.ColumnDefini ti ons> 

<ColumnDefinition Width="Auto" /> 

<ColumnDefinition Width="10*" /> 

<ColumnDefinition Width="20*" /> 

<ColumnDefinition Wi dth="Auto" /> 

</Grid.ColumnDefinitions> 

<!-- Children go here --> 

</Grid> 

Notice that the Grid collection properties are named RowDefinitions and ColumnDefinitions (plural) 
but they contain objects of type RowDefinition and ColumnDefinition (singular). You can omit the 
RowDefinitions or ColumnDefinitions for a Grid that has only one row or one column. 
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This particular Grid has three rows and four columns, and it shows the various ways that the size 
of the rows and columns can be defined. A number by itself indicates a width (or height) in pixels. 
Explicit row heights and column widths are not generally used as much as the other two options. 

The word Auto means to let the child decide. The calculated height of the row (or width of the 
column) is based on the maximum height (or width) of the children in that row (or column). 

As in HTML, the asterisk (pronounced "star" in this context) directs the Grid to allocate the 
available space. In this Grid, the height of the third row is calculated by subtracting the height of 
the first and second rows from the total height of the Grid. For the columns, the second and third 
columns are allocated the remaining space calculated by subtracting the widths of the first and fourth 
columns from the total width of the Grid. The numbers before the asterisks indicate proportions, and 
here they mean that the third column gets twice the width of the second column. 

The star values are applicable only when the size of the Grid is parent-driven! For example, 
suppose that this Grid is a child of a Stock Pan el with a vertical orientation. The StackPonel offers to the 
Grid an unconstrained infinite height. How can the Grid allocate that infinite height to its middle row? 
It cannot. The asterisk specification degenerates to Auto. 

Similarly, if a Grid is a child of a Canvas and the Grid is not given an explicit Height and Width, 
all the star specifications degenerate to Auto. The same thing happens to a Grid that does not have 
default Stretch values of Horizontal Alignment and VerticolAlignment. In the Grid example shown 
earlier, the second column might actually become wider than the third if that's what the sizes of the 
children in those columns dictate. 

However, if you have no RowDefinition objects with a star specification, the height of the 
Grid is child-driven. The Grid can go in a vertical Stock Pan el or Canvas or be given a non-default 
VerticolAlignment without weirdness happening. 

The Height property of RowDefinition and the Width property of ColumnDefinition are both of 
type GridLength, a structure defined in Windows.Ul.Xaml that lets you specify >Ac/fo or star sizes from 
code. RowDefinition also defines Min Height and MaxHeight properties, and ColumnDefinition defines 
MinWidth and MoxWidth. These are all of type double and indicate minimum and maximum sizes 
in pixels. You can obtain the actual sizes with the ActuolHeight property of RowDefinition and the 
ActualWidth property of ColumnDefinition. 

Grid also defines four attached properties that you set on the children of a Grid: Grid.Row and Grid 
.Column have default values of 0, and Grid.RowSpan and Grid.ColumnSpan have default values of 1. 
This is how you indicate the cell in which a particular child resides and how many rows and columns it 
spans. A cell can contain more than one element. 

You can nest a Grid within a Grid or put other panels in Grid cells, but the nesting of panels could 
degrade layout performance, so watch out if a deeply nested element is changing size based on an 
animation or if children are frequently being added to or removed from Children collections. You 
should probably try to avoid the layout of your page being recalculated at the video frame rate! 
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In Chapter 3, "Basic Event Handling,” I presented a Windows 8 version of WHATSIZE, the first 
program to appear in a magazine article about Windows programming. The third article about 
Windows Programming to appear in a magazine was in the May 1987 issue of Microsoft Systems 
Journal and featured a program called COLORSCR ("color scroll"). Here it is as it looked in that article 
running under a beta version of Windows 2: 



Manipulate the scrollbars to mix red, green, and blue values, and you’d see the result at the right. 
(In those days, most graphics displays didn’t have full ranges of color, so dithering was used to 
approximate colors not renderable by the device.) The value of each scrollbar is also displayed 
beneath the scrollbar. The program performed a rather crude (and heavily arithmetic) attempt at 
dynamic layout, even changing the width of the scrollbars when the window size changed. 


This seems like an ideal program to demonstrate a simple Grid. Considering the six instances of 
TextBlock and three instances of Slider required, the XAML file in the SimpleColorScroll project starts 
off with two implicit styles: 


Project: SimpleColorScroll | File: MainPage.xaml (excerpt) 

<Page.Resources 〉 

<Style TargetType="TextBlock"> 

〈Setter Property="Text" Value="00" /> 

〈Setter Property="FontSi ze" Value="24" /> 

〈Setter Property="Hori zontalA1ignment" Val ue="Center" /> 
〈Setter Property="Margi n" Val ue="0 12" /> 

</Style> 


<Style TargetType="Sl i der"> 

<Setter Property="Ori entation" Val ue="Verti cal" /> 
〈Setter Property="IsDi rectionReversed" Value="True" /> 
〈Setter Prope rty="Maxi mum" Value="255" /> 

〈Setter Property="Hori zontalA1ignment" Val ue="Center" /> 
</Style> 

</Page.Resources 〉 


I’ve decided to display the current value of each Slider in hexadecimal, so the Style for the TextBlock 
initializes the Text property to "00", which is the hexadecimal value corresponding to the minimum 
Slider position. 


148 PART Elementals 
















The Grid begins by defining three rows (for each Slider and two accompanying TextBlock labels) 
and four columns. Notice that the first three columns are all the same width but the fourth column is 
three times as wide: 


Project: SimpleColorScroll | File: MainPage.xaml (excerpt) 

<Grid Background:” {StaticResource ApplicationPageBackgroundThemeBrush}"> 
<Grid.ColumnDefinitions> 

<ColumnDefinition Width="*" /> 

<ColumnDefinition Width="*" /> 

<ColumnDefinition Width="*" /> 

<ColumnDefinition Width="3*" /> 

</Grid.ColumnDefinitions> 

<Grid.RowDefinitions> 

〈RowDefinition Height="Auto" /> 

〈RowDefinition Height="*" /> 

〈RowDefinition Hei ght="Auto" /> 

</Grid.RowDefiniti ons> 


</Grid> 


The remainder of the XAML file instantiates 10 children of the Grid. Each one has both Grid.Row 
and Grid.Column attached properties set, although these aren’t necessary for values of 0. When 
specifying attributes of Grid children, I tend to put these attached properties early but after at least 
one attribute (such as a Name or Text) that provides a quick visual identification of the element: 

Project: SimpleColorScroll | File: MainPage.xaml (excerpt) 

<Grid Background:” {StaticResource ApplicationPageBackgroundThemeBrush}"> 


<!-- Red --> 

〈TextBlock Text="Red" 

Grid.Col umn="0" 

Grid.Row="0" 

Foreground="Red" /> 

〈Slider Name="redSlider" 

Grid.Col umn="0" 

Grid.Row= M l" 

Foreground="Red" 

Val ueChanged="OnSl iderValueChanged" /> 

〈TextBlock Name="redVal ue" 

Grid.Col umn="0" 

Grid.Row="2" 

Foreground="Red" /> 
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<!-- Green --> 

<TextBlock Text="Green" 

Grid.Col umn="l" 

Grid.Row= ,, 0" 

Foreground="Green" /> 

<S1ider Name="greenSli der" 

Grid.Col umn="l" 

Grid.Row="l" 

Foreground="Green" 

Val ueChanged="OnSl iderValueChanged" /> 

<TextBlock Name="greenVal ue" 

Grid.Col umn="l" 

Grid.Row="2" 

Foreground="Green" /> 

<!-- Blue --> 

<TextBlock Text="Bl ue" 

Grid.Col umn="2" 

Crid.Row= ,, O n 
Foreground="Bl ue" /> 

〈Slider Name="bl ueSlider" 

Grid.Column="2" 

Grid.Row="l" 

Foreground="Bl ue" 

Val ueChanged="OnSl iderValueChanged" /> 

<TextBlock Name="bl ueValue" 

Grid.Col umn="2" 

Grid.Row="2" 

Foreground="Bl ue" /> 

<!-- Result --> 

〈Rectangle Grid.Col umn="3" 

Grid.Row="0" 

Grid. RowSpan="3"> 

<Rectangle.Fill> 

<SolidColorBrush x:Name="brushResul t" 

Color="Bl ack" /> 

</Rectangle.Fi11 > 

</Rectangle> 

</Crid> 


Notice that all the TextBlock and Slider elements are given Foreground property assignments based on 
what color they represent. 

The Rectangle at the bottom has the GricJ.RowSpan attached property set to 3, indicating that 
it spans all three rows. The SolidColorBrush is set to Black, so that’s consistent with the three initial 
Slider values. If you can’t get everything initialized correctly in the XAML file, the constructor of the 
code-behind file (or the Loaded event) is usually the place to do it. 
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All three Slider controls have the same handler for the ValueChanged event. That’s in the 
code-behind file: 

Project: SimpleColorScroll | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 
{ 

public MainPageO 
{ 

this .Ini ti alizeComponent(); 

} 

void OnSliderVal ueChanged(object sender, RangeBaseValueChangedEventArgs args) 

{ 

byte r = (byte) redSlider.Value; 
byte g = (byte)greenSl ider.Value; 
byte b = (byte)bl ueSlider.Value; 

redValue.Text = r.ToStri ng("X2") ; 
greenValue.Text = g.ToStri ng("X2") ; 
blueValue.Text = b.ToStri ng("X2") ; 

brushResult.Color = Color. FromArgb(255, r, g, b); 

} 

} 


The event handler could obtain the actual Slider firing the event by casting the sender argument 
and obtain the new value from the RangeBoseValueChongedEventArgs object. But regardless of which 
Slider actually changes value, the event handler needs to create a whole new Co/or value, and that 
requires all three values. The only somewhat wasteful part of this code is setting all three text values 
when only one is changing, but fixing that would require accessing the TextBlock associated with the 
particular Slider firing the event. 

Here’s one of 16,777,216 possible results: 
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Orientation and Aspect Ratios 


If you run SimpleColorScroll on a tablet and rotate it into portrait mode, the layout starts to look a 
little funny, and even if you run it in landscape mode, a snap view might cause some of the text labels 
to overlap. It might make sense to add some logic in the code-behind file that adjusts the layout 
based on the orientation or aspect ratio of the display. 

Adjusting the layout with this particular program becomes much easier if the single Grid is split 
in two, one nested in the other. The inner Grid has three rows and three columns for the Text Block 
elements and Slider controls. The outer Grid has just two children: the inner Grid and the Rectangle. In 
landscape mode, the outer Grid has two columns; in portrait mode, it has two rows. 

The XAML file for the OrientableColorScroll project has the same Style definitions as 
SimpleColorScroll. The outer Grid is shown here: 

Project: OrientableColorScroll | File: MainPage.xaml (excerpt) 

<Grid Background=" {StaticResource ApplicationPageBackgroundThemeBrush}" 

Si zeChanged="OnGri dSizeChanged"> 

<Grid.ColumnDefinitions> 

<ColumnDefinition Width="*" /> 

<ColumnDefinition x : Name="secondCol Def" Width="*" /> 

</Grid.ColumnDefiniti ons> 

<Grid.RowDefiniti ons> 

<RowDefinition Height="*" /> 

〈RowDefinition x:Name="secondRowDef" Height="0" /> 

</Grid.RowDefinitions> 


〈Grid Grid.Row="0" 

Grid.Col umn="0"> 


</Gri d> 


<!-- Result --> 

〈Rectangle Name=" rectangleResult" 

Grid.Col umn="l" 

Grid• Row="0"> 

〈 Rectangle.Fill > 

<SolidColorBrush x: Name="brushResul t" 

Color="Bl ack" /> 

</Rectangle.Fi11> 

</Rectangle> 

</Grid> 


The outer Grid has its RowDefinitions and ColumnDefinitions collections initialized for either 
contingency: two columns or two rows. In each collection, the second item has been given a name 
so that it can be accessed from code. The second row has a height of zero, so the initial configuration 
assumes a landscape mode. 
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The inner Grid (containing the TextBlock elements and Slider controls) is always in either the first 
column or first row: 

<Grid Grid. Row="0" 

Grid.Column="0"> 


</Grid> 

Setting Grid.Row and Grid.Column attributes on a Grid tag always looks a little peculiar to me. They 
refer not to the rows and columns of this Grid but to the rows and columns of the parent Grid. The 
default values of these attached properties are both zero, so these particular attribute settings aren’t 
actually required. 

The Rectangle is initially in the second column and first row: 

〈Rectangle Name=" rectangleResult" 

Grid.Column="l" 

Grid.Row="0"> 

</Rectangl e> 

In this version of the program the Rectangle has a name, so these attached properties can be 
changed from the code-behind file. This is done in the SizeChanged event handler set on the outer 
Grid: 

Project: OrientableColorScroll I File: MainPage.xaml.es (excerpt) 

void OnGridSizeChanged (object sender, SizeChangedEventArgs args) 

{ 

// Landscape mode 

if (args.NewSize.Width > args■NewSize.Height) 

{ 

secondedDef.Width = new Gri dLength(l, GridllnitType .Star); 
secondRowDef.Height = new Gri dLength(O) ; 

Grid. SetColumn(rectangleResul t, 1); 

Grid .SetRow(rectangleResult, 0); 

} 

// Portrait mode 
el se 
{ 

secondColDef.Width = new Gri dLength(O) ; 

secondRowDef.Height = new Gri dLength(l, GridUnitType. Star); 

Grid. SetColumn(rectangleResult, 0); 

Grid .SetRow(rectangleResult ， 1); 

} 

} 

This code changes the second RowDefinition and ColumnDefinition in the outer Grid. These both 
apply to the Rectangle, which has its column and row attached properties changed so that it finds 
itself in the second column (for portrait mode) or second row (for landscape mode). 
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Here’s the program running in a snap mode: 



I’ll have more to say about adjusting to snap modes in Chapter 12, "Pages and Navigation.” 


Slider and the Formatted String Converter 


In both ColorScroll programs so far, the TextBlock labels at the bottom show the current values of the 
Slider in hexadecimal. It’s not necessary to provide these values from the code-behind file. It could be 
done with a data binding from the Slider to the TextBlock. The only thing that's required is a binding 
converter that can convert a double into a two-digit hexadecimal string. 

It’s disturbing to discover that the FormottedStringConverter class I described in Chapter 4, 
"Presentation with Panels,” in connection with the WhatSizeWithBindingConverter project will not 
work in this case. You're welcome to try it out, but you’ll discover (if you don’t already know) that 
a hexadecimal formatting specification of "X2" can be used only with integral types and the Value 
property of the Slider is a double. 

However, in this case it might make more sense to write a very short ad hoc binding converter, 
particularly when you realize it can be used for two purposes, as I’ll discuss next. 


Tooltips and Conversions 


As you manipulate the Slider controls in either ColorScroll program, you’ve probably noticed 
something peculiar: The Slider has a built-in tooltip that shows the current value in a little box. That’s 
a nice feature except that this tooltip shows the value in decimal but the program insists on displaying 
the current value in hexadecimal. 
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If you think it’s great for the Slider value to be displayed in both decimal and hexadecimal, 
skip to the next section. If you’d prefer that the two values be consistent — and that they 
both display the value in hexadecimal — you’ll be pleased to know that the Slider defines a 
ThumbToolTipVolueConverter property that lets you supply a class that performs the formatting 
you want. This class must implement the IValueConverter interface, which is the same interface you 
implement to write binding converters. 

However, a converter class for the ThumbToolTipVolueConverter property can’t be as sophisticated 
as a converter class for a data binding because you don’t have the option of supplying a parameter 
for the conversion. On the plus side, the converter class can be very simple and do only what is 
required for the particular case. 

The ColorScrollWithValueConverter project defines a converter dedicated to converting a double 
to a two-character string indicating the value in hexadecimal. The name of this class is almost longer 
than the actual code: 

Project: ColorScrollWithValueConverter | File: DoubleToStringHexByteConverter.es 

using System; 

using Windows.UI.Xaml.Data; 

namespace ColorScrollWithValueConverter 
{ 

public cl ass DoubleToStringHexByteConverter : IValueConverter 
{ 

public object Convert(object value, Type targetType, object parameter, string language) 
{ 

return ((i nt) (doubl e)value).ToStri ng("X2") ; 

} 

public object ConvertBack (object value, Type targetType, object parameter, string 1 ang) 
{ 

return value; 

} 

} 

} 

This converter is suitable not only for formatting the tooltip value, but also for a binding converter 
used to display the value of the Slider in the TextBlock. The following variation of the ColorScroll 
program shows how it’s done. (To keep things simple, this version doesn’t adjust for aspect ratio.) The 
XAML file instantiates the converter in the Resources section: 

Project: ColorScrollWithValueConverter I File: MainPage.xaml (excerpt) 

<Page.Resources 〉 

<local : DoubleToStringHexByteConverter x : Key="hexConverter" /> 

</Page.Resources 〉 
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Here’s the first set of TextBlock labels and Slider. The hexConverter resource is referenced both by a 
simple StaticResource markup extension by the Slider, and by the Binding on the TextBlock, which I've 
broken into three lines for easy readability: 


Project: ColorScrollWithValueConverter I File: MainPage.xaml (excerpt) 

<!-- Red --> 

〈TextBlock Text="Red" 

Grid.Col umn="0" 

Grid.Row="0" 

Foreground="Red" /> 

〈Slider Name=" redSIider" 

Grid.Col umn="0" 

Grid.Row="l M 

ThumbToolTipValueConverter="{Stati cResource hexConverter}" 

Foreground="Red" 

Val ueChanged="OnSl iderValueChanged" /> 

<TextB1ock Text="{Bi nding El ementName=redSl ider, 

Path=Val ue, 

Converter={Stati cResource hexConverter}}" 

Grid.Col umn="0" 

Grid.Row= M 2" 

Foreground="Red" /> 

Because the VolueChanged handler no longer needs to update the TextBlock labels, that code has 
been removed, but the handler still needs to calculate a new color: 


Project: ColorScrollWithValueConverter | File: MainPage.xaml.es (excerpt) 

void OnSliderVal ueChanged(object sender, RangeBaseValueChangedEventArgs args) 

{ 

byte r = (byte) redSlider.Value; 
byte g = (by te)greenSlider.Value; 
byte b = (byte)bl ueSlider.Value; 

brushResult.Color = Color. FromArgb(255, r, g, b); 

} 


It’s possible to remove the ThumbToolTipVolueConverter from the individual Slider tags and move it 
to the Slider style: 

<Style TargetType="Sl ider"> 

〈Setter Property="Ori entation" Val ue="Verti cal" /> 

<Setter Property="IsDi rectionReversed" Val ue="True" /> 

〈Setter Property="Maximum" Value="255" /> 

〈Setter Property="Hori zontalA1ignment" Val ue="Center" /> 

〈Setter Property="ThumbToolTi pValueConverter" Val ue="{Stati cResource hexConverter}" /> 
</Style> 
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Is it possible to go another step with the data bindings and eliminate the ValueChonged handler 
entirely? That would surely be feasible if it were possible to establish bindings on the individual 
properties of Color, like so: 

<!-- Doesn't work!--> 

〈Rectangle Grid.Column="B" 

Grid.Row= M 0" 

Grid. RowSpan="3"> 

<Rectangle.Fi11 > 

<SolidColorBrush> 

<SolidColorBrush.Color> 

〈Color A="255" 

R="{Binding El ementName=redSl ider, Path=Val ue}" 

G="{Binding El ementName=greenSl ider, Path=Val ue}" 

B="{Binding El ementName=bl ueSlider, Path=Value}" /> 

</SolidColorBrush.Color> 

</SolidColorBrush 〉 

〈 /Rectangle.Fi11> 

</Rectangle> 

The big problem with this markup is that binding targets need to be backed by dependency 
properties, and the properties of Color are not. They can’t be, because dependency properties can 
be implemented only in a class that derives from DependencyObject and Color isn't a class at all. It’s a 
structure. 

The Color property of SolicJColorBrush is backed by a dependency property, and that could be 
the target of a data binding. However, in this program the Color property needs three values to be 
computed, and the Windows Runtime does not support data bindings with multiple sources. 

The solution is to have a separate class devoted to the job of creating a Color object from red, 
green, and blue values, and 111 show you how to do it in Chapter 6, "WinRT and MVVM." 

Sketching with Sliders 

I’m not going to show you a screen shot of the next program. It's called SliderSketch, and it’s a Slider 
version of a popular toy invented about 50 years ago. The user of SliderSketch must skillfully manipu¬ 
late a horizontal Slider and a vertical Slider in tandem to control a conceptual stylus that progressively 
extends a continuous polyline. I’m not going to show you a screen shot because the program is very 
difficult to use, and I’ve never managed to get beyond the baby stage. 

The XAML file defines a 2-by-2 Grid, but the screen is dominated by one cell containing a large 
Border and a Polyline. A vertical Slider is at the far left, and a horizontal Slider sits at the bottom. The 
cell in the lower-left corner is empty: 


Project: SliderSketch | File: MainPage.xaml (excerpt) 

<Grid Background:'' {StaticResource ApplicationPageBackgroundThemeBrush}"> 
<Grid.RowDefinitions> 

<RowDefinition Height="*" /> 

<RowDefinition Height="Auto" /> 

</Grid.RowDefinitions> 
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<Grid.ColumnDefinitions> 

<ColumnDefinition Wi dth="Auto" /> 
<ColumnDefinition Width="*" /> 
</Grid.ColumnDefiniti ons> 


〈Slider Name="ySl ider" 

Grid.Row="0" 

Grid.Col umn="0" 

Orientati on="Verti cal" 

IsDirectionReversed="T rue" 

Margin="0 18" 

Val ueChanged="OnSl iderValueChanged" /> 

<S1ider Name="xSl ider" 

Grid.Row= M l" 

Grid.Col umn="l" 

Margin="18 0" 

Val ueChanged="OnSl iderValueChanged" /> 

〈Border Grid. Row="0" 

Grid.Col umn="l" 

BorderBrush="{Stati cResource ApplicationForegroundThemeBrush} 
BorderThi ckness="3 0 0 3" 

Background="#C0C0C0" 

Paddi ng="24" 

Si zeChanged="OnBorderSi zeChanged"> 

<Polyline Name="polyline" 

Stroke="#404040" 

StrokeThi ckness="3" 

Points="0 0" /> 

</Border> 

</Grid> 


It is very common for a Grid to define rows and columns at the edges using Auto and then make the 
whole interior as large as possible with a star specification. The content at the edges is effectively 
docked. Windows 8 has no DockPonel, but it’s easy to mimic with Grid. 

The Margin properties on the Slider controls were developed based on experimentation. For the 
program to work intuitively, the range of Slider values should be set equal to the number of pixels 
between the minimum and maximum positions, and the Slider thumbs should be approximately even 
with the pixel for that value. The calculation of the Minimum and Maximum values for each Slider 
occurs when the size of the display area changes: 


Project: SliderSketch I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

public MainPage() 

{ 

this .InitializeComponent(); 

} 

void OnBorderSi zeChanged(object sender, SizeChangedEventArgs args) 
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Border border = sender as Border; 

xSlider.Maximum = args.NewSize.Width - border.Padding.Left 

- border.Padding.Right 
- polyline.StrokeThickness; 

ySlider.Maxi mum = args■NewSize■Height - border.Padding.Top 

- border.Padding.Bottom 
- polyline.StrokeThickness; 

} 

void OnSliderVal ueChanged(object sender, RangeBaseValueChangedEventArgs args) 

{ 

polyline.Points.Add (new Poi nt(xSlider.Value, ySlider.Value)); 

} 

} 

After all that, it’s really astonishing to see the actual "drawing” method down at the bottom: just a 
single line of code that adds a new Point to a Polyline. 

But don’t try turning your tablet upside down and shaking it to start anew. I haven’t defined an 
erase function just yet. 

The Varieties of Button Experience 

The Windows Runtime supports several buttons that derive from the ButtonBase class: 

Object 

DependencyObject 
Ul Element 
FrameworkElement 
Control 

ContentControl 

ButtonBase 

Button 

HyperlinkButton 

RepeatButton 

ToggleButton 

CheckBox 

RodioButton 

The ButtonVarieties program demonstrates the default appearances and functionality of all these 
buttons: 

Project: ButtonVarieties I File: MainPage.xaml (excerpt) 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

<StackPanel> 

<Button Content="Just a plain old Button" /> 

<HyperlinkButton Content="Hyperl inkButton" /> 
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<RepeatButton Content=" RepeatButton" /> 
<ToggleButton Content="Toggl eButton" /> 
〈CheckBox Content="CheckBox" /> 


<RadioButton Content="Radi oButton #1" /> 
<Radi oButton>Radi oButton #2</Radi oButton> 
<RadioButton> 

<RadioButton.Content 〉 

RadioButton #3 
</RadioButton.Content 〉 

</RadioButton> 

<RadioButton> 

<RadioButton.Content 〉 

<TextBlock Text="Radi oButton #4" /> 
</RadioButton.Content> 

</RadioButton> 


<ToggleSwi tch /> 

</StackPanel> 

</Grid> 

I’ve included four RodioButton instances, all with different approaches to setting the Content 
property, and they’re all basically equivalent: 



If you don’t like the look of any of these, keep in mind that you can entirely redesign them with a 
ControlTemplate that I’ll explore in Chapter 11. 

Like all FrameworkElement derivatives, the default values of the Horizontal Alignment and 
VerticalAlignment properties are Stretch. However, by the time the button is loaded, the 
Ho rizon ta I A lign ment property has been set to Left, the VerticalAlignment is Center, and a nonzero 
Padding has also been set. Although the Margin property is zero, the visuals contain a little built-in 
margin that surrounds the Border. 
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ButtonBase defines the Click event, which is fired when a finger, mouse, or stylus presses the 
control and then releases, but that behavior can be altered with the Click Mode property. Alternatively, 
a program can be notified that the button has been clicked through a command interface that I’ll 
discuss in Chapter 6. 

The classic button is Button. There’s nothing really special about HyperlinkButton except that it 
looks different as a result of a different template. RepeatButton generates a series of Click events if 
held down for a moment; this is mostly intended for the repeat behavior of the ScrollBor. 

Each click of the ToggleButton toggles it on and off. The screen shot shows the on state. Check Box 
defines nothing public on its own; it simply inherits all the functionality of ToggleButton and achieves 
a different look with a template. 

ToggleButton defines an IsChecked property to indicate the current state, as well as Checked and 
Unchecked events to signal when changing to the on or off state. In general, you'll want to install 
handlers for both these events, but you can share one handler for the job. 

The IsChecked property of ToggleButton is not a bool. It is a Nullable<bool>, which means 
that it can have a value of null. This oddity is to accommodate toggle buttons that have a third 
"indeterminate” state. The classic example is a CheckBox labeled "Bold” in a word-processing pro¬ 
gram: If the selected text is bold, the box should be checked. If the selected text is not bold, it should 
be unchecked. If the selected text contains some bold and some nonbold, however, the CheckBox 
should show an indeterminate state. You’ll need to set the IsThreeState property to true to enable 
this feature, and you’ll want to install a handler for the Indeterminate event. ToggleButton does not 
have a unique appearance for the indeterminate state; CheckBox displays a little box rather than a 
checkmark. 

With all that said, you might want to gravitate toward the ToggleSwitch control for your toggling 
needs because it’s specifically designed for touch in Windows 8 applications. Although ToggleSwitch 
does not derive from ButtonBase, I’ve included one anyway at the bottom of the list. As you can see, 
it provides default labels of "Off" and "On", but you can change those. A header is also available, as 
you’ll discover in Chapter 8, "App Bars and Popups.” 

The RadioButton is a special form of ToggleButton for selecting one item from a collection of 
mutually exclusive options. The name of the control comes from old car radios with buttons for 
preselected stations: Press a button, and the previously pressed button pops out. Similarly, when 
a RadioButton control is checked, it unchecks all other sibling RadioButton controls. The only thing 
you need to do is make them all children of the same panel. (Watch out: If you put a RadioButton in 
a Border, it is no longer a sibling with any other RadioButton. Use a template if you need a Border in 
the visuals of a RadioButton.) If you prefer to separate the RadioButton controls into multiple mutually 
exclusive groups within the same panel, a GroupName property is available for that purpose. 
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The Control class defines a Foreground property, many font-related properties, and several 
properties associated with Border, and setting these properties will change button appearance. For 
example, suppose you initialize a Button like so: 

〈Button Content="Not just a plain old Button anymore" 

Background=”Yel low" 

BorderBrush="Red" 

BorderThickness="12" 

Foreground="Bl ue" 

FontSize="48" 

FontStyle="Italic" /> 

Now it looks like this: 



However, certain visual characteristics are still governed by the template. For example, when you 
pass the mouse over this button or press it, the yellow background momentarily disappears and the 
button background changes to standard colors. Also, although you can change the Border color and 
thickness, you can’t give it rounded corners. 

Button Base derives from ContentControl, which defines a property named Content. Although the 
Content property is commonly set to text, it can be set to an Image or a panel. This is obviously very 
powerful. For example, here’s how a Button can contain a bitmap and a caption for the bitmap: 


<Button> 

<StackPanel> 

<Image Sou rce="http: //www.charlespetzold.com/pw6/PetzoldJersey.jpg" 
Width="100" /> 

<TextBlock Text="Figure 1" 

HorizontalAli gnment="Center" /> 

</StackPanel> 

</Button> 
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In Chapter 11, I’ll show you how the Content property can be set to virtually any object and how you 
can supply a template to display that object in a desirable way. 

Let’s make a simple telephone-like keypad. The keys are Button controls, and the telephone 
number that you type is displayed in a TextBlock. 

In the following XAML file, the keypad is enclosed in a Grid that is given a HorizontalAlignment 
and VerticolAlignment of Center so that it sits in the center of the screen. Regardless of the size of 
this keypad and the contents of the buttons, it should have 12 buttons of exactly the same size. 

I handled the width and the height of these buttons in two different ways. A width of 288 (that is, 3 
inches) is imposed on the keyboard Grid itself. I wanted a specific width because I realized that a user 
could type many numbers, and I didn’t want the width of the keypad to expand to accommodate an 
extra-wide TextBlock. The Height of each Button, however, is specified in an implicit style: 


Project: SimpleKeypad | File: MainPage.xaml (excerpt) 

<Grid Background：^' {StaticResource ApplicationPageBackgroundThemeBrush}"> 

<Grid HorizontalAli gnment="Center" 

VerticalAli gnment="Center" 

Width="288"> 

<Grid.Resources 〉 

<Style TargetType="Button"> 

〈Setter Property="Cl ickMode" Val ue="Press" /> 

〈Setter Property="Hori zontalAlignment" Val ue="Stretch" /> 
〈Setter Property="Hei ght" Value="72" /> 

〈Setter Property="FontSize" Value="B6" /> 

</Style> 

</Grid.Resources 〉 

<Grid.RowDefinitions> 

<RowDefinition Hei ght="Auto" /> 

〈RowDefinition Height="Auto" /> 

<RowDefinition Hei ght="Auto" /> 

<RowDefinition Hei ght="Auto" /> 

< RowDefinition Hei ght="Auto" /> 

</Grid.RowDefi niti ons> 

<Grid.ColumnDefi ni tions> 

<ColumnDefinition Width="*" /> 

<ColumnDefinition Width="*" /> 

<ColumnDefinition Width="*" /> 

</Grid.ColumnDefinitions> 

<G「id Grid. Row="0" Grid.Column="0" Grid.ColumnSpan="B"> 

<Grid.ColumnDefinitions> 

<ColumnDefinition Width="*" /> 

<ColumnDefinition Wi dth="Auto" /> 

</Grid.ColumnDefiniti ons> 
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〈Border Grid.Col umn="0" 

HorizontalAli gnment="Left"> 

<TextBlock Name=" resultText" 

HorizontalAli gnment="Ri ght" 
VerticalAli gnment="Center" 
FontSize= M 24" /> 

</Border> 


〈Button Name="del eteButton" 
Content="&#x21E6 ;" 

Grid.Column="l" 

IsEnabl ed="Fal se" 

FontFami1 y="Segoe Symbol" 

HorizontalAli gnment="Left" 
Paddi ng="0" 

BorderThi ckness="0" 

Cli ck="OnDel eteButtonCl i ck" /> 

</Grid> 


〈Button Content="l" 

Grid. Row="l" Grid.Col umn="0" 
Cli ck="OnCharButtonCl ick" /> 

〈Button Content="2" 

Grid. Row="l" Grid.Col umn="l" 
Cli ck="OnCharButtonCl ick" /> 

<Button Content="3" 

Grid. Row="l" Grid.Col umn="2" 
Cli ck="OnCharButtonCl ick" /> 

〈Button Content="4" 

Grid. Row="2" Grid.Col umn="0" 
Cli ck="OnCharButtonCl ick" /> 

<Button Content="5" 

Grid. Row="2" Grid.Col umn="l" 
Cli ck="OnCharButtonCl ick" /> 

<Button Content="6" 

Grid. Row="2" Grid.Col umn="2" 
Cli ck="OnCharButtonCl ick" /> 

〈Button Content="7" 

Grid. Row="3" Grid.Col umn="0" 
C1ick="0nCharButtonClick" /> 

〈Button Content="8" 

Grid. Row="3" Grid.Col umn="l" 
Click="OnCharButtonClick" /> 
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〈Button Content="9" 

Grid. Row="3" Grid.Col umn="2" 
Cli ck="OnCharButtonCl ick" /> 


<Button Content:"*" 

Grid. Row="4" Grid.Col umn="0" 
Cli ck="OnCharButtonCl ick" /> 

〈Button Content="0" 

Grid. Row="4" Grid.Col umn="l" 
Cli ck="OnCharButtonCl ick" /> 

<Button Content="#" 

Grid. Row="4" Grid.Col umn="2" 
Cli ck="OnCharButtonCl ick" /> 

</Grid> 

</Grid> 


The hard part is the first row. This must accommodate a TextBlock to show the typed result as well 
as a delete button. I didn’t want a very large delete button, so I made the whole first row of the Grid a 
separate Grid just for these two items. The attributes of the delete button override many of the prop¬ 
erties set in the implicit style. Notice that the delete button is initially disabled. It should be enabled 
only when there are characters to delete. 

The TextBlock was a little tricky. I wanted it to be left-justified during normal typing, but if the 
string got too long to be displayed, I wanted the TextBlock to be clipped at the left, not at the right. 
My solution was to enclose the TextBlock in a Border: 

〈Border Grid.Col umn="0" 

HorizontalAli gnment="Left"> 

〈TextBlock Name="resul tText" 

HorizontalAlignment="Ri ght" 

VerticalAli gnment="Center" 

FontSize="24" /> 

</Border> 


The Border has a fixed limit to its width: It cannot get wider than the width of the overall Grid minus 
the width of the delete button. But within that area the Border is aligned to the left. It is sized to fit 
the TextBlock, so despite its Horizontal Alignment setting, the TextBlock is also positioned at the left. 

As more characters are typed, the TextBlock gets wider until it becomes wider than the Border. At that 
point, the Horizontal Alignment setting of Right comes into play and the left part of TextBlock is what 
gets clipped. 

After that top row, everything else is smooth sailing. The implicit style helps keep the markup for 
each of the 12 numeric and symbol buttons as small as possible. 
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The code-behind file handles the Click event from the delete button and has a shared handler for 
the other 12 buttons: 

Project: SimpleKeypad | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

string inputstring = "" ; 
char[] specialChars = { 

public MainPage() 

{ 

this .InitializeComponent(); 

} 

void OnCharButtonCli ck(object sender, RoutedEventArgs args) 

{ 

Button btn = sender as Button ; 
inputString += btn.Content as string ; 

FormatTextO ; 

} 

void OnDeleteButtonCli ck(object sender, RoutedEventArgs args) 

{ 

inputString = inputString.Substring(0, inputString.Length - 1); 

FormatTextO ； 

} 

void FormatTextO 

{ 

bool hasNonNumbers = inputString.IndexOfAny(specialChars) != -1; 

if (hasNonNumbers || inputString.Length < 4 || inputString.Length > 10) 
resultText.Text = inputString; 

else if (inputString.Length < 8) 

resultText.Text = String . Format("{0}-{1}" , inputString.Substring(0, 3 )， 

inputString.Substring(3)); 

else 

resultText.Text = String. Format("({0}) {l}-{2}" , inputstring.Substring(0, 3), 

inputString.Substring(3, 3 )， 
inputString.Substring(6)); 

deleteButton.IsEnabled = inputString.Length > 0; 



The handler for the delete button removes a character from the input St ring field, and the other 
handler adds a character. Each handler then calls FormatText, which attempts to format the string as 
a telephone number. At the end of the method, the delete button is enabled only if the input string 
contains characters. 
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The OnCharButtonClick event handler uses the Content property of the button being pressed to 
determine which character to add to the string. Such an easy equivalence between the Content visuals 
of the button and the functionality of the button isn’t always available. Sometimes sharing an event 
handler among multiple controls requires that the handler extract more information from the button 
being clicked. FromeworkElement defines a Tag property of type object specifically for this purpose. 
You can set Tog to an identifying string or object in the XAML file and check it in the event handler, as 
I’ll demonstrate later in this chapter with RodioButton. 


Defining Dependency Properties 


Perhaps you’re writing an application where you want all the Button controls to display text with a 
gradient brush. Of course, you can simply define the Foreground property of each Button to be a 
LinearGrodientBrush, but the markup might start becoming a bit overwhelming. You could then try 
a Style with the Foreground property set to a LinearGradientBrush, but then each Button shares the 
same LinearGradientBrush with the same gradient colors, and perhaps you want more flexibility than 
that. 

What you really want is a Button with two properties named Colorl and Color2 that you can set to 
the gradient colors. That sounds like a custom control. It’s a class that derives from Button that creates 
a LineorGrodientBrush in its constructor and defines Colorl and Color2 properties to control this 
gradient. 

Can these Colorl and Color2 properties be just plain old .NET properties with set and get 
accessors? Yes, they can. However, defining the properties like that will limit them in some crucial 
ways. Such properties cannot be the targets of styles, bindings, or animations. Only dependency 
properties can do all that. 
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Dependency properties have a bit more overhead than regular properties, but learning how to 
define dependency properties in your own classes is an important skill. In a new project, begin by 
adding a new item to the project and select Class from the list. Give it a name of GrocJientButton, and 
in the file, make the class public and derived from Button: 

public class GradientButton : Button 
{ 

} 

Now let’s fill up that class. You will need to add some using directives along the way. 

The two new properties are named Colorl and Color2 of type Color. These two properties require 
two dependency properties of type Dependency Property named ColorlProperty and Color2Property. 
They must be public and static but settable only from within the class: 

public static DependencyProperty ColorlProperty { private set ; get; } 
public static DependencyProperty Color2Property { private set ; get; } 

These Dependency Property objects can be created in the static constructor. The 
DependencyProperty class defines a static method named Register for the job of creating 
DependencyProperty objects: 

static GradientButtonO 
{ 

ColorlProperty = 

DependencyProperty .Regi ster("Colorl" , 
typeof (Color) , 
typeof (Gradi entButton) , 

new PropertyMetadata (Col ors .White, OnColorChanged)); 

Color2Property = 

DependencyProperty .Regi ster("Color2" , 
typeof (Color) , 
typeof (Gradi entButton) , 

new PropertyMetadata(Colors .Black, OnColorChanged)); 

} 

A slightly different static method named DependencyProperty.RegisterAttoched is used to create 
attached properties. 

The first argument to DependencyProperty.Register is the text name of the property. This is 
used sometimes by the XAML parsers. The second argument is the type of the property. The third 
argument is the type of the class that is registering this dependency property. 

The fourth argument is an object of type Property Metadata. The constructor comes in two 
versions. In one version, all you need to specify is a default value of the property. In the other, you 
also specify a method that is called when the property changes. This method will not be called if the 
property happens to be set to the same value it already has. 
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The default value you specify as the first argument to the Prop ertyMe to do to constructor must 
match the type indicated in the second argument or a run-time exception will result. This is not as 
easy as it sounds. For example, it is very common for programmers to supply a default value of 0 for 
a property of type double. During compilation, the 0 is assumed to be an integer, so at run time a 
type mismatch is discovered and an exception is thrown. If you're defining a dependency property 
of type double, give it a default value of 0.0 so that the compiler knows the correct data type of this 
argument. 

An alternative approach is to define DependencyProperty objects as private static fields and then 
return those objects from the public static properties: 


static readonly DependencyProperty colorlProperty = 
DependencyProperty. Regi ster("Colorl" , 
typeof (Color) , 
typeof (GradientButton) , 

new PropertyMetadata(Colors .White, OnColorChanged)); 


static readonly DependencyProperty color2Property = 
DependencyProperty. Regi ster("Color2" , 
typeof (Color) , 
typeof (GradientButton) , 

new PropertyMetadata(Colors .B1ack, OnColorChanged)); 


public static DependencyProperty ColorlProperty 

{ 

get { return colorlProperty; } 

} 


public static DependencyProperty Color2Property 

{ 

get { return color2Property; } 

} 


The explicit static constructor isn't required. It's also possible to do it WPF or Silverlight style, where 
you don't have public static properties at all but simply define the static fields as public. Note that the 
fields are now named ColorlProperty and Color2Property: 

public static readonly DependencyProperty ColorlProperty = 

DependencyProperty .Regi ster("Colorl" , 
typeof (Color) , 
typeof (GradientButton) , 

new PropertyMetadata(Colors .White, OnColorChanged)); 

public static readonly DependencyProperty Color2Property = 

DependencyProperty .Regi ster("Color2" , 
typeof (Color) , 
typeof (GradientButton) , 

new PropertyMetadata (Col ors .Black, OnColorChanged)); 

This approach works with Windows 8, but I tend not to use it because all the public static 
DependencyProperty objects defined by the standard Windows Runtime controls are properties rather 
than fields. 
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Regardless of how you define the public static DependencyProperty objects, the GracJientButton 
class also needs regular .NET property definitions of Col or 1 and Color2. These properties are always of 
a very specific form: 

public Col or Colorl 
{ 

set { SetValue(ColorlProperty, value); } 

get { return (Color)GetValue(ColorlProperty); } 

} 

public Color Color2 
{ 

set { SetValue(Color2Property, value); } 

get { return (Color)GetValue(Color2Property); } 

} 

The set accessor always calls SetValue (inherited from the DependencyObject class), referencing the 
dependency property object, and the get accessor always calls GetValue and casts the return value to 
the proper type for the property. You can make the set accessor protected or private if you don’t want 
the property being set from outside the class. 

In my GradientButton control, I want the Foreground property to be a LineorGrodientBrush and 
I want the Colorl and Color2 properties to be the colors of the two GrodientStop objects. Two 
GradientStop objects are thus defined as fields: 

GradientStop gradientStopl, gradientStop2; 

The regular instance constructor of the class creates those objects as well as the LineorGrodientBrush 
to set it to the Foreground property: 


public GradientButtonO 
{ 

gradientStopl = new GradientStop 
{ 

Offset = 0, 

Color = this .Colorl 

}； 

gradientStop2 = new GradientStop 
{ 

Offset = 1, 

Color = this .Color2 

}； 

LinearGradientBrush brush = new LinearGradientBrushC) ; 

brush.GradientStops.Add(gradientStopl); 
brush.GradientStops.Add(gradientStop2); 

this .Foreground = brush; 

} 

Notice how the property initializers for the two GradientStop objects access the Colorl and Color2 
properties. This is how the colors in the LineorGrodientBrush are set to the default colors defined by 
the two dependency properties. 
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You’ll recall that in the definition of the two dependency properties, a method named 
OnColorChonged was specified as the method to be called whenever either the Colorl or Color2 
property changes value. Because this property-changed method is referenced in a static constructor, 
the method itself must also be static: 

static void OnColorChanged(DependencyObject obj, DependencyPropertyChangedEventArgs args) 

{ 

} 

Now this is kind of weird, because the whole point of defining this GradientButton class is to use it 
multiple times in an application, and now we Ye defining a static property that is called whenever the 
Colorl or Color2 property in an instance of this class changes. How do you know to what instance this 
method call applies? 

Easy: It’s the first argument. That first argument to this OnColorChonged method is always a 
GradientButton object, and you can safely cast it to a GradientButton and then access fields and 
properties in the particular GradientButton instance. 

What I like to do in the static property-changed method is call an instance method of the same 
name, passing to it the second argument: 

static void OnColorChanged(DependencyObject obj, DependencyPropertyChangedEventArgs args) 

{ 

(obj as GradientButton) .OnColorChanged(args); 

} 

void OnColorChanged (DependencyPropertyChangedEventArgs args) 

{ 

} 

This second method then does all the work accessing instance fields and properties of the class. 

The DependencyPropertyChangedEventArgs object contains some useful information. 

The Property property is of type D ependencyProperty and indicates the property that’s been 
changed. In this example, the Property property will be either ColorlProperty or Color2Property. 
Dependency PropertyChangedEventArgs also has properties named OldVolue and NewVolue of type 
object. 

In GradientButton, the property-changed handler sets the Color property of the appropriate 
GrodientStop object from NewValue: 

void OnColorChanged (DependencyPropertyChangedEventArgs args) 

{ 

if (args.Property == ColorlProperty) 

gradientStopl.Color = (Col or) args.NewValue; 

if (args.Property == Color2Property) 

gradientStop2.Color = (Col or)args.NewValue; 

} 
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And that’s it for GracJientButton. The only job left to do is arrange all these pieces of the 
GrodientButton class in the class in an order that makes sense to you. I like to put all fields at the top, 
static constructor next, static properties next, and then the instance constructor, instance properties, 
and all methods. Here’s the complete GrodientButton class from the DependencyProperties project: 

Project: DependencyProperties I File: GradientButton.es 

using Windows.UI; 
using Windows.UI.Xaml; 
using Windows.UI.Xaml.Controls; 
using Windows.UI.Xaml.Media; 

namespace DependencyProperties 

{ 

public cl ass GradientButton : Button 

{ 

GradientStop gradientStopl, gradientStop2; 

static GradientButton() 

{ 

ColorlProperty = 

DependencyProperty .Regi ster("Colorl" , 
typeof (Color) , 
typeof (GradientButton) , 

new PropertyMetadata(Colors .White, OnColorChanged)); 

Color2Property = 

DependencyProperty .Regi ster("Color2" , 
typeof (Color) , 
typeof (GradientButton) , 

new PropertyMetadata(Colors .Black, OnColorChanged)); 

} 

public static DependencyProperty ColorlProperty { private set ; get ; } 

public static DependencyProperty Color2Property { private set ; get ; } 

public GradientButton() 

{ 

gradientStopl = new GradientStop 

{ 

Offset = 0, 

Color = this .Colorl 

}； 

gradientStop2 = new GradientStop 

{ 

Offset = 1, 

Color = this .Color2 

}； 
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LinearGradientBrush brush = new LinearGradientBrushO ; 

brush.GradientStops.Add(gradientStopl); 
brush.GradientStops.Add(gradi entStop2); 

this .Foreground = brush; 

} 


public Col or Colorl 

{ 

set { SetValue(ColorlProperty, value); } 

get { return (Color)GetValue(ColorlProperty); } 

} 

public Color Color2 

{ 

set { SetValue(Color2Property, value); } 

get { return (Color)GetValue(Color2Property); } 

} 


static void 
{ 


OnColorChanged(DependencyObject obj, 

DependencyPropertyChangedEventArgs args) 


(obj as GradientButton) .OnColorChanged(args); 

} 


} 


void OnColorChanged (DependencyPropertyChangedEventArgs args) 

{ 

if (args.Property == ColorlProperty) 

gradientStopl.Color = (Col or)args.NewValue; 



} 


(args.Property == Color2Property) 
gradientStop2.Color = (Col or) args.NewValue; 


There are some alternate ways of writing the property-changed handler. If you specify separate 
handlers for each property, you don’t need to look at the Property property of the event arguments. 


Another option: Rather than access the NewVolue property, you can just get the value of the 
property from the class. For example: 


gradientStopl.Col or = this .Colorl; 

The Colorl property has already been set to the new value by the time the property-changed handler 
is called. 

Where are the actual values of the Colorl and Color2 properties stored? I suspect it’s some kind 
of dictionary, perhaps optimized somewhat (one would hope) but otherwise inaccessible through the 
API. The state of these properties is managed by the operating system, and the only access to their 
values is through SetVal ue and GetVolue. 
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The XAML file in this project defines a couple styles, one with Setter elements for Colorl and 
Color2, and applies these styles to two instances of GrodientButton. Any reference to GrodientButton 
in this XAML file must be preceded by the local XML namespace that is associated with the 
DependencyProperties namespace in which GrodientButton is defined. Notice the local prefix in both 
the TargetType of the Style and when the buttons are instantiated: 


Project: DependencyProperties I File: MainPage.xaml (excerpt) 
<Page 

xml ns : 1 ocal="usi ng : DependencyProperti es" 


<Page.Resources 〉 

<Style x : Key="baseButtonStyl e" TargetType="l ocal : GradientButton"> 
〈Setter Property="FontSi ze" Value="48" /> 

〈Setter Property="Hori zontalA1ignment" Val ue="Center" /> 
〈Setter Property="Margi n" Val ue="0 12" /> 

</Style> 


<Style x : Key="bl ueRedButtonStyle" 

TargetType=" local : GradientButton" 
BasedOn="{Stati cResource baseButtonStyl e}"> 
〈Setter Property="Colorl" Value="Blue" /> 
<Setter Property="Color2" Value="Red" /> 
</Style> 

</Page.Resources 〉 


<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<StackPanel> 

<local : GradientButton Content="Gradi entButton #1" 

Styl e="{StaticResource baseButtonStyl e}" /> 


<local : GradientButton Content="Gradi entButton #2" 

Styl e="{StaticResource blueRedButtonStyl e}" /> 


<local : GradientButton Content="Gradi entButton #3" 

Styl e="{StaticResource baseButtonStyle} 
Colorl="Aqua" 

Color2="Lime" /> 

</StackPanel > 

</Gri d> 


</Page> 
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The first one gets the default settings of Colorl and Color2, the second one gets the settings defined 
in the Style, and the third gets local settings Here it is: 



I want to show you an alternative way to create the GrodientButton class that lets you define the 
LinearGrodientBrush in XAML and eliminate the property-changed handlers. Interested? 

In a separate project, to create the GradientButton class, rather than adding a new item and 
picking Class from the list, add a new item, pick User Control from the list, and give it a name of 
GrodientButton. As usual you'll get a pair of files: GradientButton.xaml and GradientButton.xaml.es. 
The GradientButton class derives from UserControl. Here’s the class definition in the 
GradientButton.xaml.es file: 

public sealed partial class GradientButton : UserControl 
{ 

public GradientButton() 

{ 

this. Ini ti alizeComponent(); 

} 

} 

Change the base class from UserControl to Button: 

public sealed partial class GradientButton : Button 
{ 

public GradientButton() 

{ 

this .InitializeComponent(); 

} 

} 
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The body of this class will be very much like the first GrodientButton class except the instance 
constructor doesn’t do anything except call InitiolizeComponent. There are no property-changed 
handlers. Here’s how it looks in the DependencyPropertiesWithBindings project: 

Project: DependencyPropertiesWithBindings | File: GradientButton.xaml.es 

public sealed partial class GradientButton : Button 

{ 

static GradientButton() 

{ 

ColorlProperty = 

DependencyProperty .Regi ster("Colorl" , 
typeof (Col or ) ， 
typeof (GradientButton) , 
new PropertyMetadata(Colors .White)); 

Color2Property = 

DependencyProperty .Regi ster("Color2" , 
typeof (Col or ) ， 
typeof (GradientButton ) ， 
new PropertyMetadata(Colors. Black)); 


public static DependencyProperty ColorlProperty { private set ; get ; } 

public static DependencyProperty Color2Property { private set ; get ; } 

public GradientButton() 

{ 

this .InitializeComponent(); 

} 

public Color Colorl 

{ 

set { SetValue(ColorlProperty, value); } 

get { return (Color)GetValue(ColorlProperty); } 

} 

public Color Color2 

{ 

set { SetValue(Color2Property, value); } 

get { return (Color)GetValue(Color2Property); } 

} 

} 

When first created, the GradientButton.xaml file has a root element that indicates the class derives 
from UserControl: 

<UserControl 

x : Cl ass="DependencyPropertiesWithBindings.GradientButton" … > 


</UserControl > 
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Change that to Button as well: 

<Button 

x : Class=" DependencyPropertiesWithBindings.GradientButton" … > 

</Button> 

Normally, when you put stuff between the root tags of a XAML file, you're implicitly setting the 
Content property. But in this case we don’t want to set the Content property of the Button. We want 
to set the Foreground property of GradientButton to a UnearGmdientBmsh. This requires property- 
element tags of Button.Foreground. Here’s the complete XAML file: 

Project: DependencyPropertiesWithBindings | File: GradientButton.xaml 
〈Button 

x : Class=" DependencyPropertiesWithBindings.GradientButton" 

xml ns="http: //schemas.microsoft.com/wi nfx/2006/xaml/presentation" 

xml ns : x="http: //schemas.microsoft.com/winfx/2006/xaml" 

Name="root"> 

<Button.Foreground 〉 

<LinearGradientBrush> 

〈GradientStop 0ffset="0" 

Color="{Bi nding ElementName=root , 

Path=Colorl}" /> 

<GradientStop Offset="l" 

Color="{Bi nding ElementName=root , 

Path=Color2}" /> 

</LinearGradientBrush> 

〈 /Button■Foreground 〉 

</Button> 

Notice the cool way that the Color properties of the GrocJientStop objects are set: The root element 
is given a name of "root" so that it can be the source of two data bindings referencing the custom 
dependency properties. 

The MainPage.xaml file for this project is the same as the previous project, and the result is also 
the same. 

RadioButton Tags 

A group of RadioButton controls allows a user to choose between one of several mutually exclusive 
items. From the program’s perspective, often it is convenient that each RadioButton in a particular 
group corresponds with a member of an enumeration and that the enumeration value be identifiable 
from the RadioButton object. This allows all the buttons in a group to share the same event handler. 

The Tog property is ideal for this purpose. You can set Tog to anything you want to identify 
the control. For example, suppose you want to write a program that lets you experiment with the 
StrokeStortLineCop, StrokeEndLineCap, and StrokeLineJoin properties defined by the Shape class. 
When rendering thick lines, these properties govern the shape of the ends of the line and the shape 
where two lines join. The StrokeStortLineCap and StrokeEndLineCop properties are set to members 
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of the PenLineCop enumeration type, and the StrokeLineJoin property is set to members of the 
PenLineJoin enumeration. 


For example, one of the members of the PenLineJoin enumeration is Bevel. You might define a 
RodioButton to represent this option like so: 

<RadioButton Content="Bevel join" 

Tag="Bevel " 

... /> 

The problem is that "Bevel” is interpreted by the XAML parser as a string, so in the event handler in 
the code-behind file, you need to use switch and cose to differentiate between the different strings or 
Enum.TryPorse to convert the string into an actual PenLineJoin.Bevel value. 

A better way of defining the Tag property involves breaking it out as a property element and 
explicitly indicating that it’s being set to a value of type PenLineJoin: 

<RadioButton Content="Bevel join" 

... > 

<RadioButton.Tag> 

<PenLineDoin>Bevel</PenLi neJoi n> 

</RadioButton.Tag> 

</RadioButton> 


Of course, this is a bit wordy and cumbersome. Nevertheless, I’ve used this approach in the 
LineCapsAndJoins project. The XAML file defines three groups of RodioButton controls for the three 
Shape properties. Each group contains three or four controls corresponding to the appropriate 
enumeration members. 


Project: LineCapsAndJoins I File: MainPage.xaml (excerpt) 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Grid.RowDefinitions> 

<RowDefinition Height="*" /> 

〈RowDefinition Height="Auto" /> 

</Grid.RowDefinitions> 

<Grid.ColumnDefinitions> 

<ColumnDefinition Wi dth="Auto" /> 

<ColumnDefinition Width="*" /> 

<ColumnDefinition Wi dth="Auto" /> 

</Grid.ColumnDefiniti ons> 


<StackPanel Name="startLi neCapPanel" 

Grid. Row="0" Grid.Col umn="0" 

Margin="24"> 

<RadioButton Content="Flat start" 

Checked="OnStartLi neCapRadioButtonChecked"> 
<RadioButton.Tag> 

<PenLineCap>Flat</PenLineCap> 

</RadioButton.Tag> 

</RadioButton> 
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<RadioButton Content="Round start" 

Checked="OnStartLi neCapRadioButtonChecked"> 
<RadioButton.Tag> 

<PenLineCap>Round</PenLi neCap> 

</RadioButton.Tag> 

</RadioButton> 


<RadioButton Content="Square start" 

Checked="OnStartLi neCapRadioButtonChecked"> 
<RadioButton.Tag> 

<PenLineCap>Square</PenLi neCap> 

</RadioButton.Tag> 

</RadioButton> 


<RadioButton Content="T riangle start" 

Checked="OnStartLi neCapRadioButtonChecked"> 
<RadioButton.Tag> 

<PenLineCap>Tri angl e</PenLineCap> 

</RadioButton.Tag> 

</RadioButton> 

</StackPanel> 


<StackPanel Name="endLi neCapPanel" 

Grid. Row="0" Grid.Column="2" 

Margin="24"> 

<RadioButton Content="Flat end" 

Checked="OnEndLi neCapRadioButtonChecked"> 
<RadioButton.Tag> 

<PenLineCap>Flat</PenLi neCap> 

</RadioButton.Tag> 

</RadioButton> 


<RadioButton Content="Round end" 

Checked="OnEndLi neCapRadioButtonChecked"> 
<RadioButton.Tag> 

<PenLineCap>Round</PenLi neCap> 

</RadioButton.Tag> 

</RadioButton> 


<RadioButton Content="Square end" 

Checked="OnEndLi neCapRadioButtonChecked"> 
<RadioButton.Tag> 

<PenLineCap>Square</PenLi neCap> 

</RadioButton.Tag> 

</RadioButton> 


<RadioButton Content="T riangle End" 

Checked="OnEndLi neCapRadioButtonChecked"> 
<RadioButton.Tag> 

<PenLineCap>Tri angl e</PenLineCap> 

</RadioButton.Tag> 

</RadioButton> 

</StackPanel> 


<StackPanel Name="l ineJoinPanel" 

Grid. Row="l" Grid.Col umn="l" 
HorizontalA1i gnment="Center" 
Margin="24"> 
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<RadioButton Content="Bevel join" 

Checked="OnLi neJoinRadioButtonChecked"> 
<RadioButton.Tag> 

<PenLineDoin>Bevel</PenLi neDoi n> 

</RadioButton.Tag> 

</RadioButton> 


<RadioButton Content="Mi ter join" 

Checked="OnLi neJoinRadioButtonChecked"> 
<RadioButton.Tag> 

<PenLineDoi n>Miter</PenLi neDoin> 

</RadioButton.Tag> 

</RadioButton> 


<RadioButton Content="Round join" 

Checked="OnLi neJoinRadioButtonChecked"> 
<RadioButton.Tag> 

<PenLineDoi n>Round</PenLi neDoin> 

</RadioButton.Tag> 

</RadioButton> 

</StackPanel> 


<Polyline Name="polyli ne" 

Gn'd.Row="0" 

Grid.Col umn="l" 

Points="0 0 ， 500 1000 ， 1000 0" 

Stroke="{Stati cResource ApplicationForegroundThemeBrush}" 

StrokeThi ckness="100" 

Stretch="Fill" 

Margin="24" /> 

</Crid> 

Each of the three groups of Radio Button controls is in its own StockPonel, and all the controls within 
each Stack Pan el share the same handler for the Checked event. 

The markup doesn’t put any RodioButton in its checked state. This is the responsibility of the 
Loaded handler defined in the constructor in the code-behind file. (Oddly, when performing the 
initialization in the constructor rather than the Loaded handler, the line-join RadioButton gets 
initialized but not the other two.) 

At the bottom of the markup is a thick Polyline waiting for its StrokeStortLineCop, 
StrokeEndLineCop, and StrokeLineJoin properties to be set. This happens in the three Checked event 
handlers also in the code-behind file: 


Project: LineCapsAndJoins I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

public MainPage() 

{ 

this .InitializeComponent(); 

Loaded += (sender, args)=> 

{ 
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foreach (UIElement child in startLineCapPaneI.ChiIdren) 

(child as RadioButton) .IsChecked = 

(PenLineCap) (chi 1d as RadioButton) .Tag == polyline.StrokeStartLineCap 

foreach (UIElement child in endLineCapPanel.Children) 

(child as RadioButton) .IsChecked = 

(PenLineCap) (child as RadioButton) .Tag == polyline.StrokeEndLineCap; 

foreach (UIElement child in 1 inelloinPanel .Children) 

(child as RadioButton) .IsChecked = 

(PenLineJoin) (child as RadioButton) .Tag == polyline.StrokeLineDoin; 


}； 


} 


void OnStartLineCapRadioButtonChecked(object sender, RoutedEventArgs args) 

{ 

polyline.StrokeStartLineCap = (PenLineCap) (sender as RadioButton) .Tag; 

} 

void OnEndLineCapRadioButtonChecked (object sender, RoutedEventArgs args) 

{ 

polyline.StrokeEndLineCap = (PenLineCap) (sender as RadioButton) .Tag; 

} 

void OnLineHoinRadioButtonChecked(object sender, RoutedEventArgs args) 

{ 

pol yl i ne.StrokeLi neJoin = (PenLineJoi n)(sender as RadioButton) .Tag; 

} 


The Loaded handler loops through all the RadioButton controls in each group, setting the 
IsChecked property to true if the Tag value matches the corresponding property of the Polyline. Any 
further RadioButton checking occurs under the user’s control. The event handlers simply need to set a 
property of the Polyline based on the Tag property of the checked RadioButton. Here's the result: 



•••o 


0參籲 



FlalRol sql Tria 
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Although the markup is very explicit about setting the Tag property to a member of the 
PenLineCop or PenLineJoin enumeration, the XAML parser actually assigns the Tog an integer 
corresponding to the underlying enumeration value. This integer can easily be cast into the correct 
enumeration member, but it's definitely not the enumeration member itself. 

Much of the awkward markup in LineCapsAndJoins can be eliminated by defining a couple simple 
custom controls. These custom controls don’t need to have dependency properties; they can have just 
a very simple regular .NET property for a tag corresponding to a particular type. 

The LineCapsAndJoinsWithCustomClass shows how this works. Here’s a RadioButton derivative 
specifically for representing a PenLineCop value: 


Project: LineCapsAndJoinsWithCustomClass | File: LineCapRadioButton.es 

using Windows.UI.Xaml.Controls; 
using Windows.UI.Xaml.Media; 


namespace LineCapsAndJoinsWithCustomClass 

{ 

public class LineCapRadioButton : RadioButton 

{ 

public PenLineCap LineCapTag { set ; get; } 

} 

} 

Similarly, here's one for PenLineJoin values: 

Project: LineCapsAndJoinsWithCustomClass | File: LineJoinRadioButton.es 

using Windows.UI.Xaml.Controls; 
using Windows.UI.Xaml.Medi a; 


namespace LineCapsAndJoinsWithCustomClass 

{ 

public cl ass LineJoinRadioButton : RadioButton 


public PenLineJoin Line3oinTag { set; get; } 


Let me show you just a little piece of the XAML (the last group of three RadioButton controls) to 
demonstrate how the property-element syntax has been eliminated: 


Project: LineCapsAndJoinsWithCustomClass | File: MainPage.xaml (excerpt) 

〈StackPanel Name="l ineHoinPanel" 

Grid. Row="l" Grid.Col umn="l" 

HorizontalA1i gnment="Center" 

Margin="24"> 

<1ocal : LineDoinRadioButton Content="Bevel join" 

LineDoi nTag="Bevel " 

Checked="OnLi ne]oinRadioButtonChecked" /> 
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<local : Line3oinRadioButton Content="Miter join" 

LineJoi nTag="Mi ter" 

Checked="OnLi neJoinRadioButtonChecked" /> 

<local : LineHoinRadioButton Content="Round join" 

LineJoi nTag="Round" 

Checked="OnLi neJoinRadioButtonChecked" /> 

</StackPanel> 


You’ll notice that as you type this markup, IntelliSense correctly recognizes the LineCopTog and 
LineJoinTag properties to be an enumeration type and gives you an option of typing in one of the 
enumeration members. Nice! 


This switch to custom RadioButton derivatives mostly affects the XAML file. The code-behind file is 
pretty much the same except for somewhat less casting: 


Project: LineCapsAndJoinsWithCustomClass I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

public MainPageO 

{ 

this .Ini ti alizeComponent(); 


Loaded += (sender, args)=> 

{ 

foreach (UIElement child in startLineCapPanel.Children) 

(child as LineCapRadioButton) .IsChecked = 

(child as LineCapRadioButton) .LineCapTag == polyline.StrokeStartLineCap; 

foreach (UIElement child in endLineCapPanel.Children) 

(child as LineCapRadioButton). IsChecked = 

(child as LineCapRadioButton) .LineCapTag == polyline.StrokeEndLineCap; 


} 


}； 


foreach (UIElement child in 1ineDoinPanel.Children) 

(child as LineJoinRadioButton). IsChecked = 

(child as LineJoinRadioButton). LineDoinTag == polyline.StrokeLineJoin; 


void OnStartLineCapRadi oButtonChecked(object sender, RoutedEventArgs args) 

{ 

polyline.StrokeStartLineCap = (sender as LineCapRadioButton). LineCapTag; 

} 

void OnEndLineCapRadioButtonChecked (object sender, RoutedEventArgs args) 

{ 

polyline.StrokeEndLineCap = (sender as LineCapRadioButton) .LineCapTag; 


void OnLineJoinRadioButtonChecked(object sender, RoutedEventArgs args) 

{ 

polyline.StrokeLineJoin = (sender as LineJoinRadioButton) .LineJoinTag; 

} 

} 
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Keyboard Input and TextBox 


Keyboard input in Windows 8 applications is complicated somewhat by the on-screen touch keyboard 
that allows the user to enter text by tapping on the screen. Although the touch keyboard is impor¬ 
tant for tablets and other devices that don’t have real keyboards attached, it can also be invoked as a 
supplement to a real keyboard. 

It is vital that the touch keyboard not pop up and disappear in an annoying fashion. For this 
reason, many controls — including custom controls — do not automatically receive keyboard input. 

If they did, the system would need to invoke the touch keyboard whenever these controls received 
input focus. Consequently, if you create a custom control and install event handlers for the Key Up and 
Key Down events (or override the On Key Up and OnKeyDown methods), you’ll discover that nothing 
comes through. You need to write code that gives the control input focus. 

If you are interested in getting keyboard input from the physical keyboard only and you don’t 
care about the touch keyboard — perhaps for a program intended only for yourself or for testing 
purposes — there is a fairly easy way to do it. In the constructor of your page, obtain your application’s 
CoreWindow object: 


CoreWindow coreWindow = Window. Current.CoreWindow; 

This class is defined in the Windows.Ul.Core namespace. You can then install event handlers on this 
object for Key Down and Key Up (which indicate keys on the keyboard) as well as CharocterReceived 
(which translates keys to text characters). 

If you need to create a custom control that obtains keyboard input from both the physical 
keyboard and the touch keyboard, the process is rather more involved. You need to derive a class 
from FrameworkElementAutomotionPeer that implements the ITextProvider and IValueProvider 
interfaces and return this class in an override of the OnCreoteAutomationPeer method of your custom 
control. 

Obviously this is a nontrivial task, but I’ll provide full details in Chapter 16, "Rich Text.” 

Meanwhile, if your program needs text input, the best approach is to use one of the controls 
specifically provided for this purpose: 

■ TextBox features single-line or multiline input with a uniform font, much like the traditional 
Windows Notepad program. 

■ RichEditBox features formatted text, much like the traditional Windows WordPad program. 

■ Password Box allows a single line of masked input. 

I’ll be focusing on TextBox in this brief discussion, and I’ll provide more examples in the chapters 
ahead. Ill save RichTextBox for Chapter 16. 

TextBox defines a Text property that lets code set the text in the TextBox or obtain the current text. 
The SelectedText property is the text that’s selected (if any), and the SelectionStort and SelectionLength 
properties indicate the offset and length of the selection. If SelectionLength is 0, SelectionStort is the 
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position of the cursor. Setting the IsReadOnly property to true inhibits typed input but allows text to 
be selected and copied to the Clipboard. All cut, copy, and paste interaction occurs through context 
menus. The TextBox defines both TextChongecJ and SelectionChangecJ events. 

By default, a TextBox allows only a single line of input. Two properties can change that behavior: 

■ Normally the TextBox ignores the Return key, but setting AcceptsReturn to true causes the 
TextBox to begin a new line when Return is pressed. 

■ The default setting of the Textwrapping property is NoWrap. Setting that to Wrap causes the 
TextBox to generate a new line when the user types beyond the end of the current line. 

These properties can be set independently. Either will cause a TextBox to grow vertically as additional 
lines are added. TextBox has a built-in ScrollViewer. If you don't want the TextBox to grow indefinitely, 
set the MoxLength property. 

There is not just one touch keyboard but several, and some are more suitable for entering 
numbers or email addresses or URIs. A TextBox specifies what type of keyboard it wants with the 
InputScope property. 

The following TextBoxInputScopes program lets you experiment with different keyboard layouts, 
as well as different modes of multiline TextBox instances and (as a bonus) Password Box.. 

Project: TextBoxInputScopes | File: MainPage.xaml (excerpt) 

<Page … > 

<Page.Resources 〉 

〈Style TargetType="TextBlock"> 

〈Setter Property="FontSi ze" Value="24" /> 

〈Setter Property="Verti calA1ignment" Val ue="Center" /> 

〈Setter Property="Margi n" Value="6" /> 

</Style> 

〈Style TargetType="TextBox"> 

〈Setter Property="Wi dth" Value="320" /> 

〈Setter Property="Verti calA1ignment" Val ue="Center" /> 

〈Setter Property="Margi n" Value="0 6" /> 

</Style> 

</Page.Resources 〉 


<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Grid HorizontalAli gnment="Center"> 

<Grid.RowDefiniti ons> 


<RowDefiniti on 
<RowDefinition 
<RowDefinition 
<RowDefinition 
<RowDefinition 
<RowDefinition 
<RowDefinition 
<RowDefinition 
<RowDefinition 
<RowDefinition 


Hei ght="Auto" 
Hei ght="Auto" 
Hei ght="Auto" 
Hei ght="Auto" 
Hei ght="Auto" 
Hei ght="Auto" 
Hei ght="Auto" 
Hei ght="Auto" 
Hei ght="Auto" 
Hei ght="Auto" 


</Grid.RowDefiniti ons> 


/> 

/> 

/> 

/> 

/> 

/> 

/> 

/> 

/> 

/> 
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<Grid.ColumnDefinitions> 

<ColumnDefinition Wi dth="Auto" /> 
<ColumnDefinition Wi dth="Auto" /> 
</Grid.ColumnDefinitions> 


<!-- Multiline with Return, no wrapping --> 

<TextBlock Text="Multiline (accepts Return, no wrap):" 
Grid. Row="0" Grid.Col umn="0" /> 

<TextBox Accept sReturn="True" 

Grid. Row="0" Grid.Col umn="l" /> 

<!-- Multiline with no Return, wrapping --> 

<TextBlock Text="Multiline (ignores Return, wraps) : " 
Grid.Row="l" Grid.Col umn="0" /> 

<TextBox TextWrappi ng="Wrap" 

Grid. Row="l" Grid.Col umn="l" /> 

<!-- Multiline with Return and wrapping --> 

<TextBlock Text="Multiline (accepts Return, wraps) : " 
Grid. Row="2" Grid.Col umn="0" /> 

<TextBox AcceptsRet urn="True" 

TextWrappi ng="Wrap" 

Grid. Row="2" Grid.Col umn="l" /> 

<!-- Default input scope --> 

<TextBlock Text="Defaul t input scope:" 

Grid. Row="3" Grid.Col umn="0" /> 

<TextBox Grid. Row="3" Grid.Col umn="l" 
InputScope="Defaul t" /> 

<!-- Email address input scope --> 

<TextBlock Text="Emai1 address input scope:” 

Grid. Row="4" Grid.Col umn="0" /> 

〈TextBox Grid. Row="4" Grid.Col umn="l" 

InputScope="Emai 1SmtpAddress" /> 

<!-- Number input scope --> 

<TextBlock Text="Number input scope:" 

Grid.Row="5" Grid.Col umn="0" /> 

〈TextBox Grid. Row="5" Grid.Col umn="l" 

InputScope=" Number" /> 

<!-- Search input scope --> 

<TextBlock Text="Search input scope:" 

Grid. Row="6" Grid.Col umn="0" /> 

〈TextBox Grid. Row="6" Grid.Col umn="l" 

InputScope=" Search" /> 
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<!-- Telephone number input scope --> 

<TextBlock Text="Tel ephone number input scope:” 

Grid. Row="7" Grid.Col umn="0" /> 

〈TextBox Grid. Row="7" Grid.Col umn="l" 

InputScope="Tel ephoneNumber" /> 

<!-- URL input scope --> 
cTextBlock Text="URL input scope:" 

Grid. Row="8" Grid.Col umn="0" /> 

〈TextBox Grid. Row="8" Grid.Col umn="l" 

InputScope="Url " /> 

<!-- PasswordBox --> 

〈TextBlock Text="PasswordBox: " 

Grid. Row="9" Grid.Col umn="0" /> 

〈PasswordBox Grid. Row="9" Grid.Col umn="l" /> 

</Grid> 

</Gri d> 

</Page> 

This is a program you’ll want to experiment with before choosing a multiline mode or an Inputs cope 
value. 


Touch and Thumb 


In Chapter 13, "Touch, Etc.," I’ll discuss touch input and how you can use it to manipulate objects 
on the screen. Meanwhile, a modest control called Thumb provides some rudimentary touch 
functionality. Thumb is defined in the Windows.Ul.Xoml.Controls.Primitives namespace, and it is 
primarily intended as a building block for the Slider and Scrollbar. In Chapter 8, I’ll use it in a custom 
grid-splitter control. 

The Thumb control generates three events based on mouse, stylus, or touch movement relative 
to itself: DragStarted, DrogDelto, and DrogCompleted. The DragStorted event occurs when you put 
your finger on a Thumb control or move the mouse to its surface and click. Thereafter, DragDelta 
events indicate how the finger or mouse is moving. You can use these events to move the Thumb 
(and anything else), most conveniently on a Canvas. DragCompleted indicates a lift of a finger or the 
release of the mouse button. 

In the AlphabetBlocks program, a series of buttons labeled with letters, numbers, and some 
punctuation surrounds the perimeter. Click one, and an alphabet block appears that you can 
drag with your finger or the mouse. I know that you’ll want to send this alphabet block scurrying 
across the screen with a flick of your finger, but it won’t respond in that way. The Thumb does not 
incorporate touch inertia. For inertia, you’ll have to tap into the actual touch events beginning with 
the word Manipulation. 
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For the alphabet blocks themselves, a UserControl derivative named Block has a XAML file that 
defines a 144-pixel square image with a Thumb, some graphics, and a TextBlock: 

Project: AlphabetBlocks I File: Block.xaml 
<UserControl 

x:Cl ass="Al phabetBlocks.B1ock" 

xml ns="http: //schemas.microsoft.com/winfx/2006/xaml/presentati on" 
xml ns : x="http: //schemas.microsoft.com/winfx/2006/xaml" 
xml ns : 1 ocal="usi ng: A1 phabetBl ocks' 1 
Width="144" 

Hei ght="144" 

Name="root"> 


<Gri d> 

<Thumb DragStarted="OnThumbDragStarted" 
DragDel ta="OnThumbDragDelta" 
Margin="18 18 6 6" /> 

<!-- Left --> 

〈Polygon Points="0 6, 12 18, 12 138, 0 126” 
Fin="#E0C080" /> 

<!-- Top --> 

〈Polygon Points="6 0, 18 12, 138 12, 126 0" 
Fi"ll=''#F0D090 n /> 

<!-- Edge --> 

〈Polygon Points="6 0, 18 12 ， 12 18, 0 6" 
Fill="#E8C888" /> 


<Border BorderBrush="{Bi nding El ementName=root , Path=Fo reground}" 

BorderThi ckness="12" 

Background="#FFE0A0" 

CornerRadi us="6" 

Margin="12 12 0 0" 

IsHitTestVisible="False" /> 

<TextBlock FontFami1 y="Couri er New" 

FontSize="156" 

FontWei ght="Bol d" 

Text="{Bi nding El ementName=root , Path=Text}" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Center" 

Margin="12 18 0 0" 

IsHitTestVisible="False" /> 

</Grid> 

</UserControl > 

The Polygon shape is similar to Polyline except that it automatically closes the figure and then fills 
the figure with the brush referenced by the Fill property. 


The Thumb has DrogStorted and DragDelto event handlers installed. The two elements that sit on 
top of the Thumb — the Border and TextBlock — visually hide the Thumb but have their IsHitTestVisible 
properties set to false so that they don’t block touch input from reaching the Thumb. 
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The BorderBrush property of the Border has a binding to the Foreground property of the root 
element. Foreground, you'll recall, is defined by the Control class and inherited by UserControl and 
propagated through the visual tree. The Foreground property of the TextBlock automatically gets this 
same brush. The Text property of the TextBlock element is bound to the Text property of the control. 
UserControl doesn't have a Text property, which strongly suggests that Block defines it. 

The code-behind file confirms that supposition. Much of this class is devoted to defining a Text 
property backed by a dependency property: 


Project: AlphabetBlocks | File: Block.xaml.cs 

using Windows.UI.Xaml; 

using Windows.UI.Xaml.Controls; 

using Windows.UI.Xaml.Controls•Primitives; 


namespace AlphabetBlocks 

{ 

public sealed partial class Block : UserControl 

{ 

static int zindex; 

static Block() 

{ 

TextProperty = DependencyProperty. Register ("Text" , 
typeof(string) , 
typeof (Block) , 
new PropertyMetadata ("?")) ； 


public static DependencyProperty TextProperty { private set ; get ; } 

public static int ZIndex 

{ 

get { return ++zindex; } 


public Block() 

{ 

this .InitializeComponent(); 

} 

public string Text 

{ 

set { SetValue(TextProperty, value); } 

get { return (stri ng)GetValue(TextProperty); } 

} 


} 


} 


void OnThumbDragStarted (ob ject sender, DragStartedEventArgs args) 

{ 

Canvas . SetZIndex(thi s , ZIndex); 

} 

void OnThumbDragDelta (object sender, DragDeltaEventArgs args) 

{ 

Canvas .SetLeft (this , Canvas .GetLeft(this) + args.HorizontalChange); 
Canvas. SetTop(thi s , Canvas .GetTop(this) + args.VerticalChange); 

} 


CHAPTER 5 Control Interaction 


189 


This Block class also defines a static Zlndex property that requires an explanation. As you click 
buttons in this program and Block objects are created and added to a Canvas, each subsequent Block 
appears on top of the previous Block objects because of the way they're ordered in the collection. 
However, when you later put your finger on a Block, you want that object to pop to the top of the 
pile, which means that it should have a z-index higher than every other Block. 

The static Zlndex property defined here helps achieve that. Notice that the value is incremented 
each time it’s called. Whenever a Drag Started event occurs, which means that the user has touched 
one of these controls, the Canvas.SetZIndex method gives the Block a z-index higher than all the oth¬ 
ers. Of course, this process will break down eventually when the Zlndex property reaches its maximum 
value, but it’s highly unlikely that will happen. (The Windows Runtime imposes an arbitrary maximum 
value of 1,000,000, so if you move one block per second without stopping, the program will go out 
on an exception during the 12 th day.) 

The Drag Del to event of the Thumb reports how touch or the mouse has moved relative to itself in 
the form of HorizontalChange and VerticolChonge properties. These are simply used to increment the 
Con vos. Left and Canvas .Top attached properties. 

The MainPage.xaml file is very bare. The XAML is dominated by some text that displays the name 
of the program in the center of the page: 


Project: AlphabetBlocks I File: MainPage.xaml (excerpt) 

<Crid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}" 
Si zeChanged="OnGri dSizeChanged"> 

<TextBlock Text="Al phabet Blocks" 

FontStyl e="Ital ic" 

FontWei ght="Bold" 

FontSi ze="96" 

TextWrappi ng="Wrap" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Center" 

TextAli gnment="Center" 

Opaci ty="0. 1" /> 

<Canvas Name="buttonCanvas" /> 

<Canvas Name="blockcanvas" /> 

</Grid> 


Notice the SizeChanged handler on the Grid. Whenever the size of the page changes, the handler is 
responsible for re-creating all the Button objects and distributing them equally around the perimeter 
of the page. That code dominates that code-behind file: 


Project: AlphabetBlocks I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

const double BUTTON_SIZE = 60; 
const double BUTT0N_F0NT = 18; 

string blockChars = "ABCDEFGHIDKLMN0PQRSTUVWXYZ0123456789 !?-+*/%=" ； 

Color[] colors = { Colors .Red, Colors. Green, Colors. Orange, Colors. Blue, Colors. Purple }; 
Random rand = new RandomO; 
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public MainPage() 

{ 

this. InitializeComponent(); 

} 


void OnGridSizeChanged (object sender, SizeChangedEventArgs args) 

{ 

buttonCanvas.Children.ClearC); 

double widthFraction = args■NewSize.Width / 

(args.NewSize.Width + args.NewSize■Height); 
int horzCount = (i nt) (widthFraction * blockChars.Length / 2); 
int vertCount = (i nt) (blockChars.Length / 2 - horzCount); 
int index = 0; 

double slotWidth = (args■NewSize.Width - BUTTON—SIZE) / horzCount; 
double slotHeight = (args■NewSize■Height - BUTTON_SIZE) / vertCount + 1; 


// Across top 

for (i nt i = 0; i < horzCount; i++) 

{ 

Button button = MakeButton(index++); 

Canvas ■ SetLeft(button ， i * slotWidth); 

Canvas .SetTop(button, 0); 
buttonCanvas.Children.Add(button); 

} 

// Down right side 

for (i nt i = 0; i < vertCount; i++) 

{ 

Button button = MakeButton(index++); 

Canvas .SetLeft(button, this .ActualWidth - BUTT0N_SIZE); 

Canvas. SetTop(button, i * slotHeight); 
buttonCanvas.Children.Add(button); 

} 

// Across bottom from right 

for (i nt i = 0; i < horzCount; i++) 

{ 

Button button = MakeButton(index++); 

Canvas. SetLeft(button ， thi s. ActualWidth - i * slotWidth - BUTT0N_SIZE); 
Canvas .SetTop(button, this ■ActualHeight - BUTT0N_SIZE); 
buttonCanvas.Children.Add(button); 

} 

// Up left side 

for (i nt i = 0; i < vertCount; i++) 

{ 

Button button = MakeButton(index++); 

Canvas .SetLeft(button, 0); 

Canvas. SetTop(button, this. ActualHeight - i * slotHei ght - BUTTON_SIZE); 
buttonCanvas.Children.Add(button); 

} 
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Button MakeButton(i nt index) 

{ 

Button button = new Button 

{ 

Content = blockChars[index] .ToStringO , 

Width = BUTTON_SIZE, 

Height = BUTTON—SIZE, 

FontSize = BUTTON_FONT, 

Tag = new SolidColorBrush (colors[index % colors.Length]) 

}； 


button.Click += OnButtonClick; 
return button : 


} 


void OnButtonCli ck(object sender, RoutedEventArgs e) 

{ 

Button button = sender as Button ; 

Block block = new Block 

{ 

Text = button.Content as string, 

Foreground = button.Tag as Brush 

}； 

Canvas .SetLeft(block, this •ActualWidth / 2 - 144 * rand.NextDouble()); 

Canvas .SetTop(block, this .ActualHeight / 2 - 144 * rand.NextDouble()); 

Canvas .SetZIndex(block, Block. ZIndex); 
blockcanvas.Chi Idren.Add(block); 

} 

} 

A Block is created in the Click handler for the Button and given a random location somewhere close 
to the center of the screen. It’s the responsibility of the user to then move the blocks to discover yet 
another way to say Hello to Windows 8: 
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CHAPTER 6 

WinRT and MVVM 


I n structuring software, one of the primary guiding rules is the separation of concerns. A large 
application is best developed, debugged, and maintained by being separated into specialized layers. 
In highly interactive graphical environments, one obvious separation is between presentation and 
content. The presentation layer is the part of the program that displays controls (and other graphics) 
and interacts with the user. Underlying this presentation layer is business logic and data providers. 

To help programmers conceptualize and implement separations of concerns, architectural patterns 
are developed. In XAML-based programming environments, one pattern that has become extremely 
popular is Model-View-ViewModel, or MVVM. MVVM is particularly suited for implementing a 
presentation layer in XAML and linking to the underlying business logic through data bindings and 
commands. 

Unfortunately, books such as this one tend to contain very small programs to illustrate particular 
features and concepts. Very small programs often become somewhat larger when they are made 
to fit an architectural pattern! MVVM is overkill for a small application and may very well obfuscate 
rather than clarify. 

Nevertheless, data binding and commanding are an important part of the Windows Runtime, and 
you should see how they help implement an MVVM architecture. 


MVVM (Brief and Simplified) 

As the name suggests, an application using the Model-View-ViewModel pattern is split into three 
layers: 

■ The Model is the layer that deals with data and raw content. It is often involved with obtaining 
and maintaining data from files or web services. 

■ The View is the presentation layer of controls and graphics, generally implemented in XAML. 

■ The View Model sits between the Model and View. In the general case, it is responsible for 
making the data or content from the Model more conducive to the View. 

It’s not uncommon for the Model layer to be unnecessary and therefore absent, and that’s the case 
for the programs shown in this chapter. 
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If all the interaction between these three layers occurs through procedural method calls, a calling 
hierarchy would be imposed: 

View View Model Model 

Calls in the other direction are not allowed except for events. The Model can define an event that the 
View Model handles, and the View Model can define an event that the View handles. Events allow the 
View Model (for example) to signal to the View that updated data is available. The View can then call 
into the View Model to obtain that updated data. 

Most often, the View and View Model interact through data bindings and commands. 
Consequently, most or all of these method calls and event handling actually occur under the covers. 
These data bindings and commands serve to allow three types of interactions: 

■ The View can transfer user input to the View Model. 

■ The View Model can notify the View when updated data is available. 

■ The View can obtain and display updated data from the View Model. 

One of the goals inherent in MVVM is to minimize the code-behind file — at least on the page or 
window level. MVVM mavens are happiest when all the connections between the View and View 
Model are accomplished through bindings in the XAML file. 


Data Binding Notifications 

In Chapter 5, "Control Interaction,” you saw data bindings that looked like this: 

〈TextBlock Text="{Bi nding ElementName=s1 ider, Path=Value}" /> 

This is a binding between two FrameworkElement derivatives. The target of this data binding is the 
Text property of the TextBlock. The binding source is the Value property of a Slider identified by the 
name slider. Both the target and source properties are backed by dependency properties. This is a 
requirement for the binding target but not (as you'll see) for the source. 

Whenever the Value property of the Slider changes, the text displayed by the TextBlock changes 
accordingly. How does this work? When the binding source is a dependency property, the actual 
mechanism is internal to the Windows Runtime. Undoubtedly an event is involved. The Binding 
object installs a handler for an event that provides a notification when the Value property of the 
Slider changes, and the Binding object sets that changed value to the Text property of the TextBlock, 
converting from double to string in the process. This shouldn’t be very mysterious, considering that 
Slider has a public ValueChanged event that is also fired when the Value property changes. 

When implementing a View Model, the data bindings are a little different: The binding targets are 
still elements in the XAML file, but the binding sources are properties in the View Model class. This is 
the basic way that the View Model and the View (the XAML file) transfer data back and forth. 
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A binding source is not required to be backed by a dependency property. But in order for the 
binding to work properly, the binding source must implement some other kind of notification 
mechanism to signal to the Binding object when a property has changed. This notification does not 
happen automatically; it must be implemented through an event. 

The standard way for a View Model to serve as a binding source is by implementing the 
I Notify PropertyChanged interface defined in the System.ComponentModel namespace. This interface 
has an exceptionally simple definition: 

public interface INotifyPropertyChanged 
{ 

event PropertyChangedEventHandler PropertyChanged; 

} 


The PropertyChangedEventHandler delegate is associated with the PropertyChangedEventArgs 
class, which defines one property: PropertyName of type string. When a class implements 
INotifyPropertyChonged, it fires a PropertyChanged event whenever one of its properties changes. 

Here’s a simple example of a class that implements INotifyPropertyChanged. The single property 
named Total Score fires the PropertyChanged event when the property changes: 

public class SimpleViewModel : INotifyPropertyChanged 
{ 

double total Score; 

public event PropertyChangedEventHandler PropertyChanged; 

public double TotalScore 
{ 

set 

{ 

if (totalScore != value) 

{ 

total Score = value; 
if (PropertyChanged != null) 

PropertyChanged(thi s , new PropertyChangedEventArgs ("TotalScore")) ; 

} 

} 

get 

{ 

return totalScore; 

} 



The Total Score property is backed by the totolScore field. Notice that the TotalScore property 
checks the value coming into the set accessor against the totolScore field and fires the 
PropertyChanged event only when the property actually changes. Do not skimp on this step just 
to make these set accessors a little shorter! The event is called PropertyChanged and not 
PropertySetAndPerhapsChongedOrMaybeNot. 
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Also notice that it’s possible for a class to legally implement I Notify PropertyChcmged and not 
actually fire any PropertyChcmged events, but that would be considered very bad behavior. 

When a class has more than a couple properties, it starts making sense to define a protected 
method named OnPropertyChangecJ and let that method do the actual event firing. It’s also possible 
to automate part of this class, as you'll see shortly. 

As you design a View and View Model, it helps to start thinking of controls as visual manifestations 
of data types. Through data bindings, the controls in the View are connected to properties of 
these types in the View Model. For example, a Slider is a double, a Text Box is a string, a CheckBox or 
ToggleSwitch is a bool, and a group of RadioButton controls is an enumeration. 


A View Model for ColorScrol 


The ColorScroll programs in Chapter 5 showed how to use data bindings to update a TextBlock from 
the value property of a Slider. However, defining a data binding to change the color based on the 
three Slider values proved much more elusive. Is it possible at all? 

The solution is to have a separate class devoted to the job of creating a Color object from the 
values of Red, Green, and Blue properties. Any change to one of these three properties triggers a 
recalculation of the Color property. In the XAML file, bindings connect the Slider controls with the 
Red, Green, and Blue properties and the SolicJColorBrush with the Color property. Even if we don’t call 
this class a View Model, that's what it is. 

Here’s an RgbViewModel class that implements the INotifyPropertyChanged interface to fire 
PropertyChcmged events whenever its Red, Green, Blue, or Color properties change: 

Project: ColorScrollWithViewModel I File: RgbViewModel.es 

using System.ComponentModel; // for INotifyPropertyChanged 

using Windows.UI; // for Color 

namespace ColorScrollWithViewModel 
{ 

public cl ass RgbViewModel : INotifyPropertyChanged 


double red, green, blue; 

Color color = Col or .FromArgb(255, 0, 0, 0); 

public event PropertyChangedEventHandler PropertyChanged; 

public double Red 
{ 



if (red != value) 


red = value; 

OnPropertyChangedC'Red"); 
CalculateO ; 
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get 

{ 

return red; 

} 

} 

public double Green 

{ 

set 

{ 

if (green != value) 

{ 

green = value; 
OnPropertyChanged("Green"); 
CalculateO ; 


get 

{ 

return green; 

} 

} 

public double Blue 

{ 

set 

{ 

if (blue != value) 

{ 

blue = value; 

OnPropertyChanged("Bl ue") ; 
CalculateO ; 


get 

{ 

return blue; 

} 

} 


public Color Color 

{ 

protected set 

{ 

if (color != value) 

{ 

color = value; 
OnPropertyChanged("Color"); 


get 

{ 

return color; 


} 
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void Calculate() 

{ 

this. Col or = Color. FromArgb(255, (byte)this .Red, (byte)this .Green, (byte)this .B1ue); 

} 

protected void OnPropertyChanged(stri ng propertyName) 

{ 

if (PropertyChanged != null) 

PropertyChanged(thi s , new PropertyChangedEventArgs (propertyName)); 

} 



The On PropertyChanged method at the bottom of the class has the job of actually firing the 
PropertyChanged event with the name of the property. 

I’ve defined the Red, Green, and Blue properties as double to facilitate data bindings. These 
properties are basically input to the View Model, and they’ll probably come from controls such as 
Slider, so the double type is the most generalized. 

Each of the Red, Green, and Blue property set accessors fires a PropertyChanged event and then 
calls Calculate, which sets a new Color value, which causes another PropertyChanged event to be fired 
for the Color property. The Color property itself has a protected set accessor, indicating that this class 
isn’t designed to calculate Red, Green, and Blue values from a new Co/or value. (I’ll explore this issue 
shortly.) 

The RgbViewModel class is part of the ColorScrollWithViewModel project. The MainPage.xaml file 
instantiates the RgbViewModel in its Resources section. 


Project: ColorScrollWithViewModel I File: MainPage.xaml (excerpt) 
<Page.Resources 〉 

<local : RgbViewModel x:Key="rgbViewModel" /> 
</Page.Resources 〉 


Notice the namespace prefix of local. 

Defining the View Model as a resource is one of two basic ways that a XAML file can get access to 
the object. As was demonstrated in Chapter 2, "XAML Syntax,” a class included in a Resources section 
is instantiated only once and shared among all StoticResource references. That behavior is essential for 
an application such as this, in which all the bindings need to reference the same object. 

Each of the Slider controls is similar. Only one is shown here: 

Project: ColorScrollWithViewModel | File: MainPage.xaml (excerpt) 

<!-- Red --> 

<TextBlock Text="Red" 

Grid.Col umn="0" 

Grid.Row="0" 

Foreground="Red" /> 


198 PART Elementals 


〈Slider Grid.Col umn="0" 

Grid.Row="l" 

Val ue="{Bi nding Source={Stati cResource rgbViewModel }, 

Path=Red , 

Mode=TwoWay}" 

Foreground="Red" /> 

<TextBlock Text="{Bi nding Source={Stati cResource rgbViewModel }, 

Path=Red , 

Converter={Stati cResource hexConverter}}" 

Grid.Col umn="0" 

Grid.Row="2" 

Foreground="Red" /> 

Notice that the Slider element no longer has a Name attribute because no other element in the XAML 
file refers to this element, and neither does the code-behind file. There’s no VolueChanged event 
handler because that’s not needed either. The code-behind file contains nothing except a call to 
InitializeComponent. 

Take careful note of the binding on the Slider: 


<S1ider 

Val ue="{Bi ndi ng Source={StaticResource rgbViewModel }, 

Path=Red , 

Mode=TwoWay}" ... /> 

This binding is a little long, so I’ve broken it into three lines. It does not specify an ElementName 
because it’s not referencing another element in the XAML file. Instead, it’s referencing an object 
instantiated as a XAML resource, so it must use Source with StaticResource. The syntax of this binding 
implies that the binding target is the Value property of the Slider and the binding source is the Red 
property of the RgbViewModel instance. 


Does this seem backward? Shouldn’t the Slider be providing a value to RgbViewModel? 

Yes, but RgbViewModel must be a binding source rather than a target. It can’t be a binding target 
because it has no dependency properties. Despite the syntax implying that Value is the binding 
target, in reality we want the Slider to provide a value to the Red property. For this reason, the Mode 
property of Binding must be set to TwoWoy, which means 


■ an updated source value causes a change to the target property (the normal case for a data 
binding), and 

■ an updated target value causes a change to the source property (which is actually the essential 
transfer here). 

The default Mode setting is OneWoy. The only other option is OneTime, which means that the 
target is updated from the source property only when the binding is established. With OneTime, no 
updating occurs when the source property later changes. You can use OneTime if the source has no 
notification mechanism. 
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Also notice that the Text Block showing the current value now has a binding to the RgbViewModel 
object: 

<TextB1ock Text="{Bi nding Source={Stati cResource rgbViewModel }, 

Path=Red , 

Converter={Stati cResource hexConverter}}" ... /> 

This binding could instead refer directly to the Slider as in the previous project, but I thought it 
would be better that it also refer to the RgbViewModel instance. The default OneWoy mode is fine 
here because data only needs to go from the source to the target. 

The OneWay mode is also good for the binding on the Color property of the SolidColorBrush: 


Project: ColorScrollWithViewModel | File: MainPage.xaml (excerpt) 

〈Rectangle Grid.Column="3" 

Grid.Row= M 0" 

Grid■RowSpan="3"> 

〈 Rectangle.Fill> 

<SolidColorBrush Color="{Bi nding Source={Stati cResource rgbViewModel }, 

Path=Color}" /> 

</Rectangle.Fi11> 

</Rectangle> 

The SolidColorBrush no longer has an x:Nome attribute because there’s nothing in the code- 
behind file that refers to it. 

Of course, the code in the RgbViewModel class is much longer than the ValueChangecJ event 
handler we’ve managed to remove from the code-behind file. I warned you at the outset that MVVM 
is overkill for small programs. Even in larger applications, often there’s an initial price to pay for 
cleaner architecture, but the separation of presentation and business logic usually has long-term 
advantages. 

In the RgbViewModel class I made the set accessor of Color protected so that it can be accessed 
only from within the class. Is this really necessary? Perhaps the Color property can be defined so that 
an external change to the property causes new values of the Red, Green, and Blue properties to be 
calculated: 

public Color Color 
{ 

set 

if (color != value) 

{ 

color = value; 

0nPropertyChanged("Co1or"); 
this. Red = color.R; 
this. Green = color.G; 
this. Blue = color.B; 

} 

} 

get 

{ 

return color; 

} 

} 
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At first this might seem like asking for trouble because it causes recursive property changes and 
recursive calls to OnPropertyChonged. But that doesn’t happen because the set accessors do nothing 
if the property is not actually changing, so this should be safe. 

But it’s actually flawed. Suppose the Color property is currently the RGB value (0, 0, 0) and it’s set 
to value (255,128, 0). When the Red property is set to 255 in the code, a PropertyChanged event is 
fired, but now Color (and color) is set to (255, 0, 0), so the code here continues with Green and Blue 
being set to the new color values of 0. 

Rather than guard against re-entry, try searching for a change in logic that does what you want. 
This version works OK, even though it causes a flurry of PropertyChanged events: 

public Color Color 



if (color != value) 

{ 

color = value; 
OnPropertyChanged("Color"); 
this .Red = value. R; 
this .Green = value. G; 
this. Blue = value.B; 


get 


return color; 


I’ll make the set accessor of Color property public in the next version of the program. 


Syntactic Shortcuts 


You might have concluded from the RgbViewModel code that implementing INotifyPropertyChonged 
is a bit of a hassle, and that's true. To make it somewhat easier, Visual Studio creates a BindobleBase 
class in the Common folder for projects of type Grid App and Split App. (Don’t confuse this class with 
the BindingBose class from which Binding derives.) 

However, Visual Studio does not create this BindobleBase class in the Blank App project. But let's 
take a look at it and see if we can learn anything. 

The BindobleBase class is defined in a namespace that consists of the project name followed by a 
period and the word Common. Stripped of comments and attributes, here’s what it looks like: 

public abstract class BindableBase : INotifyPropertyChanged 
{ 

public event PropertyChangedEventHandler PropertyChanged; 
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protected bool SetProperty<T>(ref T storage, T value, 

[Cal 1 erMemberName] String propertyName = null) 

{ 

if (object .Equals(storage, value)) return false; 
storage = value; 

this .OnPropertyChanged(propertyName); 
return true; 

} 

protected void OnPropertyChangedC [Cal 1erMemberName] string propertyName = null) 
{ 

var eventHandler = this .PropertyChanged; 
if (eventHandler != null) 

{ 

eventHandler (this , new PropertyChangedEventArgs (propertyName)); 

} 



A class that derives from BindobleBose calls Set Property in the set accessor of its property 
definitions. The signature for the SetProperty method looks a little hairy, but it’s very easy to use. For 
a property named Red of type double, for example, you would have a backing field defined like this: 

double red; 

You call SetProperty in the set accessor like so: 

SetPrope rty<double>( ref red, value, "Red") ; 

Notice the use of CallerMemberNome in BindobleBase. This is an attribute added to .NET 4.5 that 
C# 5.0 can use to obtain information about code that’s calling a particular property or method, which 
means that you can call SetProperty without that last argument. If you're calling SetProperty from the 
set accessor of the Red property, the name will be automatically provided: 

SetPrope rty<double>( ref red, value); 

The return value from SetProperty is true if the property is actually changing. You'll probably 
want to use the return in logic that does something with the new value. For the next project, called 
ColorScrollWithDataContext, IVe created an alternate version of RgbViewModel that steals some code 
from BindobleBase, and IVe given Color a public set accessor: 

Project: ColorScrollWithDataContext | File: RgbViewModel.es 

using System.ComponentModel; 

using System.Runtime.Compi1erServices; 

using Windows.UI; 

namespace ColorScrollWithDataContext 
{ 

public cl ass RgbViewModel : INotifyPropertyChanged 
{ 

double red ， green, blue; 
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Color color = Color. FromArgb(255, 0, 0, 0); 


public event PropertyChangedEventHandler PropertyChanged; 

public double Red 

{ 

set 

{ 

if (SetProperty<doubl e>(ref red, value, "Red")) 
Calculate(); 

} 

get 

{ 

return red; 

} 

} 

public double Green 

{ 

set 

{ 

if (SetProperty<double>(ref green, value)) 
Calculate(); 

} 

get 

{ 

return green; 

} 

} 

public double Blue 

{ 

set 

{ 

if (SetProperty<doubl e>(ref blue, value)) 
Calculate(); 

} 

get 

{ 

return blue; 

} 

} 

public Color Color 

{ 

set 

{ 

if (SetProperty<Col or>(ref color, value)) 

{ 

this. Red = value .R; 
this .Green = val ue.G; 
this. Blue = value.B; 

} 

} 

get 

{ 


return color; 


CHAPTER 6 WinRT and MVVM 


203 


} 


} 


void Calculate() 

{ 

this .Color = Color. FromArgb(255, (byte)this. Red, (byte)this .Green, (byte)this .B1ue); 

} 


protected bool 
{ 


SetProperty<T>(ref T storage, T value, 

[Cal 1 erMemberName] string propertyName = null) 


if (object .Equals(storage, value)) 
return false; 


storage = value; 

OnPropertyChanged(propertyName); 
return true; 


} 


protected void OnPropertyChanged(stri ng propertyName) 

{ 

if (PropertyChanged != null) 

PropertyChanged(thi s , new PropertyChangedEventArgs (propertyName)); 

} 

} 


This form of the I Notify PropertyChonged implementation is somewhat cleaner and certainly 
sleeker. I’ll use this version in the ColorScrollWithDataContext project in the next section. 

The DataContext Property 

So far you’ve seen three ways to specify a source object in a binding: ElementNome, RelotiveSource, 
and Source. ElementNome is ideal for referencing a named element in XAML, and RelotiveSource 
allows a binding to reference a property in the target object. (RelotiveSource actually has a more 
important but also more esoteric use that you’ll discover in Chapter 11, "The Three Templates.’’）The 
third option is the Source property, which is generally used with StoticResource for accessing an object 
in the Resources collection. 

There’s a fourth way to specify a binding source: If ElementNome, RelotiveSource, and Source are all 
null, the Binding object checks the DataContext property of the binding target. 

The DataContext property is defined by FrameworkElement, and it has the wonderful (and 
essential) characteristic of propagating down through the visual tree. Not many properties propagate 
through the visual tree in this way. Foreground and all the font-related properties do so, but not many 
others. DataContext is one of the big exceptions to the rule. The constructor of a code-behind file can 
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instantiate a View Model and set that instance to the DataContext of the page. Here’s how it’s done in 
the MainPage.xaml.es file of the ColorScrollWithDataContext project: 


Project: ColorScrollWithDataContext | File: MainPage.xaml.es 

public MainPage() 

{ 

this. InitializeComponent(); 

this. DataContext = new RgbViewModel (); 

// Initialize to highlight color 

(thi s .DataContext as RgbViewMode' ).Color = 

new UlSetti ngs() .UIE1ementColor(UIEl ementType .Highlight); 

} 


Instantiating the View Model in code might be necessary or desirable for one reason or another. 
Perhaps the View Model has a constructor that requires an argument. That’s something XAML 
can’t do. 

Notice that I’ve also taken the opportunity to test the settability of the Color property by 
initializing it to the system highlight color. 

One big advantage to the DataContext approach is the simplification of the data bindings. Because 
they no longer require Source settings, they can look like this: 


〈Slider Val ue="{Binding Path=Red , Mode=TwoWay}" ... /> 

Moreover, if the Path item is the first item in the binding markup, the Path= part can be removed: 
〈Slider ■■■ Val ue="{Binding Red, Mode=TwoWay}" ... /> 

Now that’s a simple Binding syntax! 

You can remove the Path= part of any binding specification regardless of the source, but only if 
Path is the first item. Whenever I use Source or ElementName, I prefer for that part of the Binding 
specification to appear first, so 111 drop Path= only when the DataContext comes into play. 

Here’s an excerpt from the XAML file showing the new bindings. They’ve become so short that I’ve 
stopped breaking them into multiple lines: 


Project: ColorScrollWithDataContext I File: MainPage.xaml (excerpt) 

<!-- Red --> 

<TextBlock Text="Red" 

Grid.Column="0" 

Grid.Row= M 0" 

Foreground="Red" /> 

〈Slider Grid.Column="0" 

Grid.Row="l" 

Value="{Bi nding Red , Mode=TwoWay}" 
Foreground="Red" /> 
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<TextBlock Text="{Bi nding Red , Converter={Stati cResource hexConverter}}" 

Grid.Col umn="0" 

Gn'd.Row= M 2" 

Foreground="Red" /> 

<!-- Result ——> 

〈Rectangle Gn'd.Column="3" 

Grid.Row="0" 

Grid■RowSpan="3"> 

〈 Rectangle.Fill> 

<SolidColorBrush Color="{Bi nding Color}" /> 

</Rectangle.Fill> 

</Rectangle> 

It’s possible to mix the two approaches. For example, you can instantiate the View Model in the 
Resources collection of the XAML file: 


<Page.Resources 〉 


<1ocal : RgbViewModel x:Key="rgbViewModel" /> 


</Page.Resources 〉 


Then at the earliest convenient place in the visual tree, you can set a DataContext property: 

<Grid … DataContext="{Stati cResource rgbViewModel }" … > 

Or: 

<Grid … DataContext="{Bi nding Source={Stati cResource rgbViewModel }}” … > 

The second form is particularly useful if you want to set the DataContext to a property of the View 
Model. You’ll see examples when I begin discussing collections in Chapter 11. 

Bindings and TextBox 

One of the big advantages to isolating underlying business logic is the ability to completely revamp 
the user interface without touching the View Model. For example, suppose you want a color-selection 
program that is similar to ColorScroll but where each color component is entered in a TextBox. Such a 
program might be a little clumsy to use, but it should be possible. 

The ColorTextBoxes project has the same RgbViewModel class as the ColorScrollWithDataContext 
program. The code-behind file has the same constructor as that project as well: 


Project: ColorTextBoxes I File: MainPage.xaml.es (excerpt) 

public MainPage() 

{ 

this .InitializeComponentC); 

this .DataContext = new RgbViewModel (); 
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// Initialize to highlight color 

(thi s .DataContext as RgbViewModel ).Color = 

new UlSetti ngs() .UIE1ementCol or(UIEl ementType .Highlight); 


The XAML file instantiates three TextBox controls and defines data bindings between the Red, 
Green, and Blue properties of RgbViewModel: 


Project: ColorTextBoxes | File: MainPage.xaml (excerpt) 

<Page … > 


<Page.Resources 〉 

〈Style TargetType="TextBlock"> 

〈Setter Property="FontSi ze" Value="24" /> 

〈Setter Property="Margi n" Value="24 0 0 0" /> 

〈Setter Property="Verti calA1ignment" Val ue="Center" /> 
</Style> 

<Style TargetType="TextBox"> 

〈Setter Property="Margi n" Value="24 48 96 48" /> 
〈Setter Property="Verti calA1ignment" Val ue="Center" /> 
</Style> 

</Page.Resources 〉 


<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Grid.ColumnDefini ti ons> 

<ColumnDefinition Width="*" /> 

<ColumnDefinition Width="*" /> 

</Grid.ColumnDefini ti ons> 

<Crid Grid.Col umn="0"> 

<Grid.RowDefinitions> 

<RowDefinition Hei ght="Auto" /> 

<RowDefinition Hei ght="Auto" /> 

〈RowDefinition Hei ght="Auto" /> 

</Grid.RowDefinitions> 

<Grid.ColumnDefinitions> 

<ColumnDefinition Wi dth="Auto" /> 

<ColumnDefinition Width="*" /> 

</Grid.ColumnDefiniti ons> 

<TextBlock Text="Red: " 

Grid.Row="0" 

Grid.Col umn="0" /> 

〈TextBox Text="{Binding Red , Mode=TwoWay}" 

Grid.Row= M 0 M 
Grid.Column="l" /> 

<TextBlock Text="Green: " 

Grid.Row="l" 

Grid.Col umn="0" /> 
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〈TextBox Text="{Binding Green , Mode=TwoWay}" 
Grid.Row="l" 

Grid.Col umn="l" /> 

<TextBlock Text="Blue: " 

Grid.Row="2" 

Grid.Col umn="0" /> 

〈TextBox Text="{Binding Blue ， Mode=TwoWay}" 
Grid.Row= M 2" 

Grid.Col umn="l" /> 

</Grid> 


<!-- Result --> 

<Rectangle Grid.Col umn="l"> 

<Rectangle.Fi11 > 

<SolidColorBrush Color="{Bi nding Color}" /> 

</Rectangle.Fi11 > 

</Rectangle> 

</Gri d> 

</Page> 

When the program runs, the individual TextBox controls are initialized with color values, all the 
necessary data conversions being performed behind the scenes: 



Now tap one of the TextBox controls, and try entering another number. Nothing happens. Now 
tap another TextBox, or press the Tab key to shift the input focus to the next TextBox. Aha! Now the 
number you entered in the first TextBox has finally been acknowledged and used to update the color. 

As you experiment with this program, you’ll find that the Windows Runtime is extremely lenient 
about accepting letters and symbols in these text strings without raising exceptions but that any new 
value you type registers only when the TextBox loses input focus. 
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This behavior is by design. Suppose a View Model bound to a Text Box is using a Model to update 
a database through a network connection. As the user types text into a Text Box — perhaps making 
mistakes and backspacing — do you really want each and every change going over the network? For 
that reason, user entry in the Text Box is considered to be completed and ready for processing only 
when the TextBox loses input focus. 

Unfortunately, there’s currently no option to change this behavior. Nor is there any way to include 
validation in these data bindings. If the TextBox binding behavior is unacceptable, and if you prefer 
not duplicating TextBox logic with a control of your own, the only real choice you have is abandoning 
bindings for this case and using the TextChanged event handler instead. 

The ColorTextBoxesWithEvents project shows one possible approach. The project still uses the 
same RgbViewModel class. The XAML file is similar to the previous project except that the TextBox 
controls now have names and TextChanged handlers assigned: 


Project: ColorTextBoxesWithEvents | File: MainPage.xaml (excerpt) 

<TextBlock Text="Red: " 

Grid.Row^O” 

Grid.Column="0" /> 

〈TextBox Name=" redTextBox" 

Grid.Row="0 M 
Grid.Column="l" 

Text="0 M 

TextChanged="OnTextBoxTextChanged" /> 

〈TextBlock Text="Green: " 

Grid.Row="l" 

Grid.Column="0" /> 

<TextBox Name="greenTextBox" 

Grid.Row="l" 

Grid.Column="l" 

Text="0 M 

TextChanged="OnTextBoxTextChanged" /> 

<TextBlock Text="Blue: " 

Grid-Row^Z” 

Grid.Column="0" /> 

〈TextBox Name="bl ueTextBox" 

Grid.Row="2" 

Grid.Column="l" 

Text="0 M 

TextChanged="OnTextBoxTextChanged" /> 

The Rectangle, however, still has the same data binding as in the earlier programs. 

Because weYe replacing two-way bindings, not only do we need event handlers on the TextBox 
controls, but we need to install a handler for the PropertyChanged event of RgbViewModel. Updating 
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a TextBox when a View Model property changes is fairly easy, but I also decided I wanted to actually 
validate the text entered by the user: 

Project: ColorTextBoxesWithEvents | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

RgbViewModel rgbViewModel; 

Brush textBoxTextBrush; 

Brush textBoxErrorBrush = new SolidColorBrush(Colors .Red); 

public MainPage() 

{ 

this. InitializeComponent(); 

// Get TextBox brush 

textBoxTextBrush = this .Resources ["TextBoxForegroundThemeBrush"] as SolidColorBrush ; 

// Create RgbViewModel and save as field 
rgbViewModel = new RgbViewModel (); 

rgbViewModel.PropertyChanged += OnRgbViewModelPropertyChanged; 
this .DataContext = rgbViewModel; 

// Initialize to highlight color 

rgbViewModel.Color = new UlSettings().UIElementColor(UIElementType.Highlight); 

} 

void OnRgbViewModelPropertyChanged(object sender, PropertyChangedEventArgs args) 

{ 

switch (args.PropertyName) 

{ 

case "Red" : 

redTextBox.Text = rgbViewModel.Red.ToString("F0"); 
break; 

case "Green" : 

greenTextBox.Text = rgbViewModel.Green.ToString("F0"); 
break; 

case "B1ue" : 

blueTextBox.Text = rgbViewModel.B1ue.ToString("F0"); 
break; 



void OnTextBoxTextChanged (object sender, TextChangedEventArgs args) 

{ 

byte value; 

if (sender == redTextBox && Validate(redTextBox, out value)) 
rgbViewModel.Red = value; 

if (sender == greenTextBox && Validate(greenTextBox, out value)) 
rgbViewModel.Green = value; 
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} 


if (sender == blueTextBox && Validate(blueTextBox, out value)) 
rgbViewModel.B1ue = value; 


bool Validate (TextBox txtbox, out byte value) 

{ 

bool valid = byte .TryParse(txtbox.Text, out value); 

txtbox.Foreground = valid ? textBoxTextBrush : textBoxErrorBrush; 

return valid; 



The Validate method uses the standard TryPorse method to convert the text into a byte value. If 
successful, the View Model is updated with the value. If not, the text is displayed in red, indicating a 
problem. 

This works well except when the numbers being entered are preceded with leading blanks or 
zeros. For example, suppose you type 0 in the first Text Box. That’s a valid byte, so the Red property in 
RgbViewModel is updated with this value, which triggers a PropertyChanged method, and the TextBox 
is assigned a Text value of "0". No problem. Now type a 5. The TextBox contains "05”. The TryPorse 
method considers this to be a valid byte string, and the Red property is updated with the value 5. 

Now the PropertyChanged handler sets the Text property of the TextBox to the string 〃 5〃，replacing 
"05”. But the cursor location is not changed, so it’s in front of the 5 instead of being after the 5. 

Perhaps the best way to prevent this problem is to ignore PropertyChanged events from the View 
Model while setting a property in the View Model from the TextChanged handler. You can do this 
with a simple flag: 


bool blockViewModelUpdates; 


void OnRgbViewModelPropertyChanged(object sender, PropertyChangedEventArgs args) 

{ 

if (blockViewModelUpdates) 
return ; 

} 

void OnTextBoxTextChanged (object sender, TextChangedEventArgs args) 

{ 

blockViewModelUpdates = true ; 
blockViewModelUpdates = false; 

} 

You’ll probably also want to clean up the displayed values when each TextBox loses input focus. 

In some cases, data entry validation might more properly be under the jurisdiction of View Model 
rather than the View. 
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Buttons and MVVM 


At first, the idea that you can use MVVM to eliminate most of a code-behind file seems valid only for 
controls that generate values. The concept starts to crumble when you consider buttons. A Button 
fires a Click event. That Click event must be handled in the code-behind file. If a View Model is actu¬ 
ally implementing the logic for that button (which is likely), the Click handler must call a method in 
the View Model. That might be architecturally legal, but it’s still rather cumbersome. 

Fortunately, there’s an alternative to the Click event that is ideal for MVVM. This is sometimes 
informally referred to as the "command interface. 〃 ButtonBase defines properties named Command 
(of type /Command) and CommandParameter (of type object) that allow a Button to effectively make 
a call into a View Model through a data binding. Command and CommandParameter are both backed 
by dependency properties, which means they can be binding targets. Command is almost always 
the target of a data binding. CommandParameter is optional. It’s useful for differentiating between 
buttons bound to the same Command object, and it’s usually treated like a Tag property. 

Perhaps you’ve written a calculator application where you’ve implemented the engine as a View 
Model that’s set as the DataContext. The calculator button for the + (plus) command might be 
instantiated in XAML like so: 

<Button Content="+" 

Command="{Bi nding CalculateCommand}" 

CommandParameter="add" /> 

What this means is that the View Model has a property named ColculoteCommond of type 
I Comm and, perhaps defined like this: 

public ICommand CalculateCommand { protected set ; get; } 

The View Model must initialize the ColculoteCommond property by setting it to an instance of a class 
that implements the ICommand interface, which is defined like so: 

public interface ICommand 
{ 

void Execute(object param); 

bool CanExecute (object param) 

event EventHandl er<object> CanExecuteChanged; 

} 

When this particular Button is clicked, the Execute method is called in the object referenced by 
ColculoteCommond with an argument of "odd". This is how a Button basically makes a call right into 
the View Model (or rather, the class containing that Execute method). 

The other two-thirds of the ICommand interface contain the phrase "can execute" and involve 
the validity of the particular command at a particular time. If this command is not currently valid — 
perhaps the calculator can’t add right now because no number has been entered — the Button should 
be disabled. 
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Here’s how it works: As the XAML is being parsed and loaded at run time, the Command property 
of the Button is assigned a binding to (in this example) the CalculoteCommoncJ object. The Button 
installs a handler for the CanExecuteChanged event and calls the Can Execute method in this object 
with an argument (in this example) of "odd". If Con Execute returns false, the Button disables itself. 
Thereafter, the Button calls Con Execute again whenever the CanExecuteChanged event is fired. 

To include a command in your View Model, you must provide a class that implements the 
ICommond interface. However, it’s very likely that this class needs to access properties in the View 
Model class, and vice versa. 

So you might wonder: Can these two classes be one and the same? 

In theory, yes they can, but only if you use the same Execute and CanExecute methods for all the 
buttons on the page, which means that each button must have a unique CommandParometer so that 
the methods can distinguish between them. But let me show you the standard way of implementing 
commands in a View Model. 


The DelegateCommand Class 

Let’s rewrite the SimpleKeypad application from Chapter 5 so that it uses a View Model to 
accumulate the keystrokes and generate a formatted text string. Besides implementing the 
I Notify PropertyChanged interface, the View Model will also process commands from all the buttons 
in the keypad. There will be no more Click handlers. 

Here’s the problem: For the View Model to process button commands, it must have one or more 
properties of type ICommancJ, which means that we need one or more classes that implement the 
ICommond interface. To implement ICommond, these classes must contain Execute and CanExecute 
methods and the CanExecuteChanged event. Yet, the bodies of these methods undoubtedly need to 
interact with the other parts of the View Model. 

The solution is to define all the Execute and CanExecute methods in the View Model class but with 
different and unique names. Then, a special class can be defined that implements ICommancJ but that 
actually calls the methods in the View Model. 

This special class is often named DelegateCommand, and if you search around, you’ll find several 
somewhat different implementations of this class, including one in Microsoft's Prism framework, 
which helps developers implement MVVM in Windows Presentation Foundation (WPF) and Silverlight. 
The version here is my variation. 

DelegateCommand implements the ICommond interface, which means it has Execute and 
CanExecute methods and the CanExecuteChanged event, but it turns out that DelegateCommand 
also needs another method to fire the CanExecuteChanged event. Let’s call this additional method 
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RoiseConExecuteChonged. The first job is to define an interface that implements ICommond plus this 
additional method: 


Project: KeypadWithViewModel | File: IDelegateCommand.es 
using System.Windows .Input; 

namespace KeypadWithViewModel 

{ 

public interface IDelegateCommand : ICommand 

{ 

void RaiseCanExecuteChangedO; 

} 

} 

The DelegateCommancJ class implements the IDelegoteCommond interface and makes use of a 
couple simple (but useful) generic delegates defined in the System namespace. These predefined 
delegates have the names Action and Func with anything from 1 to 16 arguments. The Func delegates 
return an object of a particular type; the Action delegates do not. The Action<object> delegate 
represents a method with a single object argument and a void return value; this is the signature of the 
Execute method. The Func<object, bool> delegate represents a method with an object argument that 
returns a bool] this is the signature of the Can Execute method. DelegateCommancJ defines two fields 
of these types for storing methods with these signatures: 

Project: KeypadWithViewModel | File: DelegateCommand.es 
using System; 

namespace KeypadWithViewModel 

{ 

public cl ass DelegateCommand : IDelegateCommand 

{ 

Acti on<object> execute; 

Funccobject ， bool> canExecute; 

// Event required by ICommand 

public event EventHandler CanExecuteChanged; 

// Two constructors 

public DelegateCommand (Acti on<ob ject> execute, Func<object , bool> canExecute) 

{ 

this. execute = execute; 

this .canExecute = canExecute; 

} 

public DelegateCommand (Acti on<ob ject> execute) 

{ 

this. execute = execute; 

this .canExecute = this .AlwaysCanExecute; 

} 

// Methods required by ICommand 
public void Execute(object param) 

{ 

executeCparam); 

} 
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public bool CanExecute (object param) 

{ 

return canExecute(param); 

} 

// Method required by IDelegateCommand 
public void RaiseCanExecuteChanged() 

{ 

if (CanExecuteChanged != null) 

CanExecuteChanged(thi s , EventArgs. Empty); 

} 

// Default CanExecute method 
bool AlwaysCanExecute (object param) 

{ 

return true; 

} 



This class implements Execute and CanExecute methods, but these methods merely call the methods 
saved as fields. These fields are set by the constructor of the class from constructor arguments. 

For example, if the calculator View Model has a command to calculate, it can define the 
ColculoteCommand property like so: 

public IDelegateCommand CalculateCommand { protected set ; get ; } 

The View Model also defines two methods named ExecuteColculote and CanExecuteCalculate: 

void ExecuteCal culate(object param) 

{ 

} 

bool CanExecuteCalculate (object param) 

{ 

} 

The constructor of the View Model class creates the CalculoteCommand property by instantiating 
DelegateCommand with these two methods: 


this .CalculateCommand = new Del egateCommand (ExecuteCal culate, CanExecuteCalculate); 

Now that you see the general idea, let’s look at the View Model for the keypad. For the text 
entered into and displayed by the keypad, this View Model defines two properties named Inputstring 
and the formatted version, DisployText. 

The View Model also defines two properties of type I DelegateCommand named 
AdcJCharacterCommond (for all the numeric and symbol keys) and DeleteChorocterCommoncJ. These 
properties are created by instantiating DelegateCommand with the methods ExecuteAddChorocter, 
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ExecuteDeleteCharacter, and ConExecuteDeleteCharacter. There's no ConExecuteAddChorocter 
because the keys are always valid. 

Project: KeypadWithViewModel | File: KeypadViewModel.es 
using System; 

using System.ComponentModel; 

using System.Runtime.Compi1erServices; 

namespace KeypadWithViewModel 

{ 

public cl ass KeypadViewModel : INotifyPropertyChanged 

{ 

string inputstring = "" ; 
string displayText = "" ; 
char[] specialChars = { 

public event PropertyChangedEventHandler PropertyChanged; 

// Constructor 

public KeypadViewModel() 

{ 

this .AddCharacterCommand = new Del egateCommand(ExecuteAddCharacter); 
this .DeleteCharacterCommand = 

new DelegateCommand (ExecuteDeleteCharacter, CanExecuteDeleteCharacter); 

} 

// Public properties 
public string Inputstring 
{ 

protected set 

{ 

bool previousCanExecuteDeleteChar = this. CanExecuteDeleteCharacter (nul1 ); 

if (this .SetProperty<stri ng>(ref inputString, value)) 

{ 

this .DisplayText = FormatText(inputString); 

if (previousCanExecuteDeleteChar != this. CanExecuteDeleteCharacter (nul1 )) 
this .DeleteCharacterCommand.RaiseCanExecuteChanged(); 


get { return inputString; } 

} 

public string DisplayText 

{ 

protected set { this .SetProperty<stri ng>(ref displayText, value); } 
get { return displayText; } 

} 
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// ICommand implementations 

public IDelegateCommand AddCharacterCommand { protected set ; get ; } 


public IDelegateCommand DeleteCharacterCommand { protected set ; get; } 

// Execute and CanExecute methods 
void ExecuteAddCharacter (object param) 

{ 

this .InputString += param as string; 

} 

void ExecuteDeleteCharacter (object param) 

{ 

this .InputString = this .InputString.Substring(0, this .InputString.Length - 1) 

} 


bool CanExecuteDeleteCharacter (object param) 

{ 

return this .InputString.Length > 0; 

} 

// Private method called from InputString 
string FormatText(stri ng str) 

{ 

bool hasNonNumbers = str.IndexOfAny(specialChars) != -1; 
string formatted = str; 

if (hasNonNumbers || str.Length < 4 || str.Length > 10) 


else if (str.Length < 8) 

{ 

formatted = String. Format("{0}-{1}", str.Substring(0, 3 )， 

str■Substring(3)); 

} 

else 

{ 

formatted = String. Format (" ({0}) {l}-{2}" , str.Substring(0, 3), 

str.Substring(3, 3 )， 
str■Substring(6)); 

} 

return formatted; 

} 


protected bool SetProperty<T>(ref T storage, T value, 

[Cal 1erMemberName] string propertyName = null) 


{ 


if (object .Equals(storage, value)) 
return false; 


storage = value; 

OnPropertyChanged(propertyName); 
return true; 
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} 

protected void OnPropertyChanged(stri ng propertyName) 

{ 

if (PropertyChanged != null) 

PropertyChanged(thi s , new PropertyChangedEventArgs (propertyName)); 

} 

} 

} 

The ExecuteAddChoracter method expects that the parameter is the character entered by the user. 
This is how the single command is shared among multiple buttons. 

The CanExecuteDeleteChorocter returns true only if there are characters to delete. The delete 
button should be disabled otherwise. But this method is called initially when the binding is first 
established and thereafter only if the CanExecuteChonged event is fired. The logic to fire this event 
is in the set accessor of Inputstring, which compares the ConExecuteDeleteCharocter return values 
before and after the input string is modified. 

The XAML file instantiates the View Model as a resource and then defines a Data Context in the 
Grid. Notice the simplicity of the Command bindings on the thirteen Button controls and the use of 
CommandPorometer on the numeric and symbol keys: 


Project: KeypadWithViewModel 丨 File: MainPage.xaml (excerpt) 

<Page … > 


<Page.Resources 〉 

<local : KeypadViewModel x:Key="viewModel " /> 
</Page.Resources 〉 


<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}" 
DataContext="{Stati cResource viewModel }"> 

<Grid HorizontalAli gnment="Center" 

VerticalA1i gnment="Center" 

Width="288"> 

<Grid.Resources 〉 

<Style TargetType=" Button"> 

〈Setter Property="Cl ickMode" Val ue="Press" /> 

〈Setter Property="Hori zontalAlignment" Val ue="Stretch" /> 
〈Setter Property="Hei ght" Value="72" /> 

〈Setter Property="FontSi ze" Value="36" /> 

</Style> 

</Grid.Resources 〉 


<Grid.RowDefinitions> 

〈RowDefinition Height="Auto" /> 
〈RowDefinition Height="Auto" /> 
<RowDefinition Height="Auto" /> 
〈RowDefinition Height="Auto" /> 
<RowDefinition Height="Auto" /> 
</Grid.RowDefinitions> 
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<Grid.ColumnDefiniti ons> 

<ColumnDefinition Width="*" /> 
<ColumnDefinition Width="*" /> 
<ColumnDefinition Width="*" /> 
</Grid.ColumnDefiniti ons> 


〈Grid Grid. Row="0" Grid.Col umn="0" Grid.Col umnSpan="3"> 
<Grid.ColumnDefi ni ti ons> 

<ColumnDefinition Width="*" /> 

<ColumnDefinition Wi dth="Auto" /> 

</Grid.ColumnDefini tions> 


〈Border Grid.Col umn="0" 

HorizontalAli gnment="Left"> 

<TextBlock Text="{Binding DisplayText}" 
HorizontalAlignment="Ri ght" 
VerticalA1i gnment="Center" 
FontSize="24" /> 

</Border> 


〈Button Content="Mx21E6 ;" 

Command="{Bi nding DeleteCharacterCommand} 
Grid.Column="l" 

FontFami ly="Segoe Symbol" 

HorizontalAli gnment="Left" 

Padding="0" 

BorderThickness="0" /> 

</Gri d> 

〈Button Content="l" 

Command="{Bi nding AddCharacterCommand}" 
CommandParameter="l" 

Grid.Row="l" Grid.Col umn= ,, 0 M /> 


〈Button Content="#" 

Command="{Bi nding AddCharacterCommand}" 

CommandParameter="#" 

Grid. Row="4" Grid.Col umn="2" /> 

</Grid> 

</Gri d> 

</Page> 

The really boring part of this project is the code-behind file, which now contains nothing but a call 
to InitializeComponent. 

Mission accomplished. 
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CHAPTER 7 

Asynchronicity 


T hese days programmers are discouraged from making frequent use of message boxes, but I’m 
sure we can all acknowledge how useful they can be to give the user some important information 
in a very direct manner, or to obtain a vital Yes, No, or Cancel. 

The Windows Runtime supports a message box with the MessageDialog class, and it’s actually 
quite versatile: Up to three buttons can be labeled with whatever text you’d like. However, there is no 
Show method in this class. The expected Show method has been replaced with ShowAsync. 

That Async suffix is short for "asynchronous," and that's a very important sequence of five letters 
in the Windows Runtime. It’s not just a change of name; it’s a change in how you use the method and 
ultimately a change in philosophy in how we code for modern operating systems like Windows 8. 


Threads and the User Interface 


Like applications for earlier versions of Windows, a Windows 8 program is structured much like a state 
machine. Following initialization, the program usually sits dormant in memory waiting for events. Very 
often these events signal user interaction with the program, but sometimes they signal systemwide 
changes, such as a switch in the orientation of the display. 

It’s important that applications process events as quickly as possible and then return control back 
to the operating system to wait for more events. If an application doesn’t process an event quickly, 
it could become unresponsive and annoy the user. For this reason, applications should relegate very 
lengthy jobs to secondary threads of execution. The thread devoted to the user interface should 
remain free and unencumbered of heavy processing. 

But what if a particular method call in the Windows Runtime itself takes a long time to complete? 

Is the application programmer expected to anticipate that problem and put that call in a secondary 
thread? 


No, that seems unreasonable. For that reason, when the Microsoft developers were designing the 
Windows Runtime, they attempted to identify any method call that could require more than 50 mil¬ 
liseconds to return control to the application. Approximately 10-15 percent of the Windows Runtime 
qualified. These methods were made asynchronous, meaning that the methods themselves spin off 
secondary threads to do the lengthy processing. They return control back to the application very 
quickly and later notify the application when they’ve completed. 
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You’ll encounter asynchronous methods most often when working with file I/O or accessing the 
Internet. But they also turn up when invoking dialog boxes implemented in Windows 8, such as 
MessogeDiolog and a couple file pickers you’ll see later in this chapter. All asynchronous methods in 
the Windows Runtime are identified with the A sync suffix, and they all have similar definition pat¬ 
terns. Fortunately, working with asynchronous methods has become much less onerous as a result of 
powerful .NET libraries and enhancements to the C# programming language. 

A skill in asynchronous programming is likely to become much more important in the years ahead. 
In consumer computers of the past, all threads of execution ran on the same processor. It was the 
job of the operating system to switch quickly among these threads, giving the appearance that they 
run simultaneously. In recent years, however, computers frequently have multiple processors, usually 
occupying the same chip in a multicore configuration. This type of hardware allows different threads 
to run on different processors. 

Some types of heavy computational tasks — such as array processing — can take advantage of 
multiple processors by running a bunch of calculations in parallel. To support asynchronous and 
parallel processing, support was added to .NET called the Task-based Asynchronous Pattern, or TAP, 
which is centered around the Task class in the System.Threading.Tasks namespace. This part of .NET 
can be accessed by Windows Runtime applications coded in C# and Visual Basic, and it is much more 
powerful and versatile than the asynchronous support in the Windows Runtime itself. 

Working with MessageDialog 

To get a feel for the syntax of using asynchronous functions, let’s look at MessageDialog. The 
MessogeDiolog constructor accepts a message string and (optionally) a title and by default displays a 
single button named "Close.” This is suitable for delivering some essential information to the user. You 
also have the option of defining up to three custom buttons by using UlCommond objects. Here’s an 
example from a project called HowToAsyncl: 

MessageDialog msgdlg = new MessageDi alogC'Choose a color" , "How To Async #1") ; 
msgdlg.Commands.Add (new UICommand("Red", null ， Colors. Red)); 
msgdlg.Commands.Add (new UICommand("Green " ， null, Colors .Green)); 
msgdlg.Commands.Add (new UICommand("Bl ue" , null ， Colors .Blue)); 

The first argument to the UlCommond constructor is the text that appears on the button, and the 
third argument is an ID of type object that can be anything you like to identify the button. I’ve chosen 
to use the actual Color value indicated by the label. I’ll discuss the second argument shortly. 

The UlCommond class implements the lUICommond interface. When the MessageDialog informs 
your program what button has been pressed, it does so with an object of type lUICommand. 

The asynchronous processing occurs when you call the ShowAsync method. The method has 
no arguments and returns quickly back to the application. The message box itself is handled by a 
secondary thread of execution. Here’s the call: 

IAsyncOperation<IUICommand> asyncOp = msgdlg.ShowAsyncC); 
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What ShowAsync returns is an object that implements the generic lAsyncOperotion interface. The 
generic argument is the lUICommond interface, which means that the MessogeDialog returns an 
object of type lUICommand, except not right away. It can’t return a value until the user presses one of 
the buttons and the MessogeDialog is dismissed, and the MessogeDialog hasn’t even been displayed 
yet! For that reason, an object like lAsyncOperotion is sometimes called a "future" or a "promise." 

I A syn cOper a tion<T> derives from the lAsyndnfo interface, which defines methods named Cancel 
and Close and properties named Id, Status, and ErrorCode. The I A syncOpera tion< T > interface 
additionally defines a property named Completed, which is a delegate of type 
AsyncOperotionCompletedHondler<T>. 

What you set to this Completed property is a callback method in your code. Although Completed 
is defined as a property, it functions like an event, in that it signals something of interest to your pro¬ 
gram. (The difference is that an event can have multiple handlers, but a property can have only one.) 
Here’s how it’s done: 


asyncOp.Completed = OnMessageDialogShowAsyncCompleted : 

If the method in your program that calls ShowAsync and sets the Completed handler contains any 
additional code, that code will be executed next. Only after the method calling ShowAsync returns 
control back to the operating system will the MessogeDialog be displayed: 



How To Async #1 

Choose a color 



This MessogeDialog is handled by a thread created specifically for this purpose. Although the user 
interface of your program is disabled while the MessogeDialog is displayed, the user interface thread 
of your program is not blocked. It can continue to do work. 

You’ll notice the button labeled Red is colored differently from the others. This is the default 
button that is effectively triggered when the user presses Enter. You can change which button is the 
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default using the DefaultCommandlndex property of MessogeDiolog. You can also select a button to 
be triggered when the user presses Esc by setting the CancelCommondlndex property. 

When the user presses a button, the message box is dismissed and the Completed callback method 
in your program is called. The first argument to this method is the same object that ShowAsync 
returned, but I’ve given it a somewhat different name [asynclnfo) because now it actually has some 
information for us: 

void OnMessageDialogShowAsyncCompleted (IAsyncOperation<IUICommand> asynclnfo, 

AsyncStatus asyncStatus) 

{ 

// Get the Color value 

IUICommand command = asyncInfo.GetResults(); 

Color clr = (Color) command.Id; 

} 


This lAsyncOperotion argument has a property named Status of type AsyncStatus, an enumeration 
with four members: Started, Completed, Canceled, or Error. This value is reproduced as the second 
argument to the Completed handler. If an error has occurred — which is not relevant for the 
MessageDialog class but certainly possible when dealing with file I/O or Internet access — the 
ErrorCode property of lAsyncOperotion is an object of type Exception. 

In the general case, you should check that the status is Completed before calling GetResults. The 
GetResults method returns an object of the same type as the generic argument to lAsyncOperotion, in 
this case an object of type IUICommand indicating the pressed button. From this, you can get the Id 
property that comes from the third argument to the UlCommand constructor. In this code it can be 
cast to a Color value. 

And now, perhaps, the program can use this color to set the background brush on a Grid: 
contentGrid.Background = new SolidColorBrush(cl r); 

Not so fast! 

When your program calls ShowAsync, the MessogeDiolog class creates a secondary thread of 
execution to display the message box and buttons. When the user presses a button, the Completed 
handler in your code is called, but it runs in that secondary thread, and you cannot access user 
interface objects from this secondary thread! 

For any particular window, there can be only one application thread that handles user input and 
displays controls and graphics that interact with this input. This "Ul thread" (as it’s called) is conse¬ 
quently very important and very special to Windows applications because all interaction with the user 
must occur through this thread. But only code that runs in that thread can access the elements and 
controls that constitute the user interface. 

This prohibition can be generalized: DependencyObject is not thread safe. Any object based on a 
class that derives from DependencyObject can only be accessed by the thread that creates that object. 
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In this particular example, a Color value can be obtained by a secondary thread of execution 
because Color is a structure and hence does not derive from DependencyObject. However, any code 
that applies that Color value to the user interface must run in the Ul thread. 

Fortunately, there's a way to do it. To compensate for the fact that it is not thread safe, 
DependencyObject has a property named Dispatcher that returns an object of type CoreDispotcher. 
This Dispatcher property is an exception to the rule that prohibits you from accessing a 
DependencyObject from another thread. The HosThreodAccess property of CoreDispotcher lets you 
know if you can access this particular DependencyObject from the thread in which the code is running. 
If you can't (and even if you can), you can put a chunk of code on a queue for execution by the thread 
that created the object. 

You queue up some code to run on the user interface thread by calling the RunAsync method 
defined by CoreDispotcher. This is another asynchronous method, and you pass to it a method that 
you want to run in the user interface thread: 

void OnMessageDialogShowAsyncCompleted (IAsyncOperation<IUICommand> asynclnfo, 

AsyncStatus asyncStatus) 

{ 

this .Dispatcher.RunAsync(CoreDi spatcherPriority .Normal, OnDispatcherRunAsyncCal1 back); 

} 

void OnDispatcherRunAsyncCal 1 back() 

{ 

contentGrid.Background = new SolidColorBrush(cl r); 

} 

Usually the CoreDispotcher object obtained from the Dispatcher property is not saved as a variable; 
the RunAsync method is just called on the Dispatcher property itself, as shown here. The call¬ 
back you pass to the RunAsync method can safely access elements in the user interface. How¬ 
ever, notice that there’s no way to pass arbitrary information to this method, which means that 
OnMessogeDiologShowAsyncCompleted must first save the Color value as a field. 

It doesn’t matter from which user interface element you obtain this CoreDispotcher object; all the 
user interface objects are created in the same Ul thread, so they all work identically. 

Although I haven’t shown it in this code, the RunAsync method of CoreDispotcher returns an object 
of lAsyncAction: 

IAsyncAction asyncAction = this. Dispatcher.RunAsync(CoreDi spatcherPriority .Normal, 

OnDispatcherRunAsyncCal1 back); 

IAsyncAction is very similar to the lAsyncOperotion object returned from the ShowAsync method 
of MessogeDialog. Both of them implement the lAsyndnfo interface. The big difference is that 
lAsyncOperotion is used for asynchronous methods that need to return something to the program 
(hence the generic argument), while IAsyncAction is used for asynchronous methods that do not 
return information. 
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Here’s an interface hierarchy: 


lAsyndnfo 

lAsyncAction 

lAsyncAction Wi th Progress < TProg ress > 

IA syn cOp era tion <TResult> 

IA syn cOp era tion With Progress< TResult, TProgress 〉 

Some asynchronous methods are capable of reporting progress while performing the 
asynchronous job, and those have their own interfaces. 

At any rate, you can set a Completed handler on the lAsyncAction object returned from the 
Run Async method of CoreDispatcher and use that for accessing the user interface: 

void OnMessageDialogShowAsyncCompleted (IAsyncOperation<IUICommand> asynclnfo, 

AsyncStatus asyncStatus) 

{ 

■ ■ ■ 

lAsyncAction asyncAction = this .Dispatcher.RunAsync(CoreDi spatcherPriori ty. Normal, 

OnDispatcherRunAsyncCal1 back); 

asyncAction.Completed = OnDispatcherRunAsyncCompleted; 

} 

void OnDispatcherRunAsyncCompl eted(IAsyncActi on asynclnfo, AsyncStatus asyncStatus) 

{ 

contentGrid.Background = new Sol idColorBrush(cl r); 

} 

This particular Completed handler runs in the user interface thread. But there’s no real purpose for 
this additional method; you can’t set the second argument of the Run Async method to null, so you 
still need that method as well. 

Here’s the entire HowToAsyncl project. The XAML file has a button specifically for invoking the 
MessageDialog: 


Project: HowToAsyncl | File: MainPage.xaml (excerpt) 

<Grid Name="contentGri d" 

Background=" {StaticResource ApplicationPageBackgroundThemeBrush}"> 

<Button Content="Show me a MessageDialog!" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Center" 

Cli ck="OnButtonCl ick" /> 


</Grid> 
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Nothing in the code-behind file should be surprising at this point: 


Project: HowToAsyncl I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

Color clr; 

public MainPageO 

{ 

this. Initi alizeComponent(); 

} 

void OnButtonCli ck(object sender, RoutedEventArgs args) 

{ 

MessageDialog msgdlg = new MessageDialog ("Choose a color" , "How To Async #1") ; 
msgdlg.Commands.Add (new UICommand("Red", null, Colors .Red)); 
msgdlg.Commands.Add (new UICommand("Green", null, Colors .Green)); 
msgdlg.Commands.Add (new UICommand("Bl ue" , null ， Colors. B1ue)); 

// Show the MessageDialog with a Completed handler 
IAsyncOperation<IUICommand> asyncOp = msgdlg.ShowAsyncC); 
asyncOp.Completed = OnMessageDialogShowAsyncCompleted; 

} 


void OnMessageDialogShowAsyncCompleted (IAsyncOperation<IUICommand> asynclnfo, 

AsyncStatus asyncStatus) 

{ 

// Get the Color value 

IUICommand command = asynclnfo■GetResults(); 
clr = (Color) command.Id; 


// Use a Dispatcher to run in the UI thread 

IAsyncAction asyncAction = this .Dispatcher.RunAsync(CoreDi spatcherPriority .Normal, 

OnDispatcherRunAsyncCal1 back); 


void OnDispatcherRunAsyncCal1back() 

{ 

// Set the background brush 

contentGrid.Background = new SolidColorBrush(cl r); 



The optional second argument to the UlCommond constructor is a callback method of the del¬ 
egate type UlCommond Invoked Handler: 

void OnMessageDialogCommand (IUICommand command) 

{ 

} 

This callback runs in the UI thread, and for that reason it represents perhaps an easier alternative to 
get the button pressed by the user. 
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Callbacks as Lambda Functions 


To more gracefully handle callback methods is one reason why C# 3.0 added a support of 
anonymous methods, also known as lambda functions or lambda expressions. All the callback logic 
in HowToAsyncl can be moved to lambda functions in the Click handler, and the Color value doesn’t 
need to be saved as a field. This is shown in the HowToAsync2 project: 


Project: HowToAsync2 I File: MainPage.xaml.es (excerpt) 

void OnButtonCli ck(object sender, RoutedEventArgs args) 

{ 

MessageDialog msgdlg = new MessageDialog ("Choose a color" , "How To Async #2") ; 
msgdlg.Commands.Add (new UICommand("Red", null, Colors .Red)); 
msgdlg.Commands.Add (new UICommand("Green", null, Colors .Green)); 
msgdlg.Commands.Add (new UICommand("Bl ue" , null, Colors. Blue)); 

// Show the MessageDialog with a Completed handler 
IAsyncOperation<IUICommand> asyncOp = msgdlg.ShowAsync(); 
asyncOp.Completed = (asynclnfo, asyncStatus)=> 

{ 

// Get the Color value 

IUICommand command = asyncInfo.GetResultsO; 

Color clr = (Color) command.Id; 

// Use a Dispatcher to run in the UI thread 

IAsyncAction asyncAction = this .Dispatcher.RunAsync(CoreDi spatcherPriori ty. Normal, 

C)=> 

{ 

// Set the background brush 

contentGrid.Background = new SolidCol orBrush(cl r); 

}); 

}； 

} 


Although everything has been moved to the single Click handler, obviously this code does not run 
all at once. The Completed handler for the MessageDialog runs only after the box is dismissed, and the 
callback of the CoreDispotcher class runs only when the user interface thread is available for running 
some code. 

This particular assemblage of two lambda functions isn't too bad, but it’s easy for nested lambda 
functions to get rather more entangled. Once you start working with file I/O, for example, often 
several steps must be executed in sequence, many of which are asynchronous. The nested lambda 
functions start piling up and begin obscuring the actual structure of the code. Lambda functions are 
certainly convenient, but they are often not very readable. In some cases, lambda functions can even 
turn common procedural code inside out and make it difficult to execute a simple return statement or 
deal with an exception. 

Another solution is desperately needed. Fortunately, it exists. 
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The Amazing await Operator 


The C# 5.0 keyword await allows us to work with asynchronous operations as if they were relatively 
normal method calls without callback methods. Here’s the code I’ve been using to obtain the 
lAsyncOperation object: 

IAsyncOperation<IUICommand> asyncOp = msgdlg.ShowAsyncO; 

The earlier programs used a callback method to obtain that lUICommond object indicating the 
pressed button. The await operator effectively extracts that lUICommand object directly from the 
lAsyncOperation object: 

lUICommand command = await asyncOp; 

Very often, these two statements are combined into one, as shown in the HowToAsync3 program, 
which is functionally equivalent to the first two programs: 


Project: HowToAsync3 | File: MainPage.xaml.es (excerpt) 

async void OnButtonCli ck(object sender, RoutedEventArgs args) 

{ 

MessageDialog msgdlg = new MessageDialog ("Choose a color" , "How To Async #3") ; 
msgdlg.Commands.Add (new UICommand("Red", null, Colors .Red)); 
msgdlg.Commands.Add (new UICommand("Green", null, Colors .Green)); 
msgdlg.Commands.Add (new UICommand("Bl ue" , null, Colors. Blue)); 

// Show the MessageDialog 

lUICommand command = await msgdlg.ShowAsyncO ； 

// Get the Color value 
Color clr = (Color) command.Id; 

// Set the background brush 

contentGrid.Background = new SolidColorBrush(cl r); 

} 

Nice, wouldn’t you say? 

The await keyword is a full-fledged C# operator, and it’s perfectly legal to embed it in more 
complex code. This single statement does the work of the last three statements shown above: 

contentGrid. Background = new SolidCo1orBrush((Color) (await msgdlg■ ShowAsyncO) .Id); 

Let me emphasize again: HowToAsync3 is functionally identical to the two previous programs. Yet, 
the syntax is considerably cleaner, and it all results from the owoit operator. The await operator seems 
to bypass all the messy callback stuff and return the lUICommand directly. It looks like magic, but 
much of the messy implementation details are now hidden. The C# compiler recognizes the pattern 
of the ShowAsync method and generates the callback and the GetResults call. 

What the await operator essentially does is break up the method in which it’s used and turn it into 
a state machine. This OnButtonClick method begins executing normally until ShowAsync is called and 
the owoit appears. Despite its name, that owoit does not wait until the operation completes. Instead, 
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the Click handler is exited at that point. Control returns to Windows. Other code on the program’s 
user interface thread can then run, as can the MessageDialog itself. When the MessogeDialog is 
dismissed and a result is ready and the Ul thread is ready to run some code, execution of the Click 
handler continues with the assignment to the lUICommond object. The method then proceeds until 
the next owoit operator, if there is one. 

However, there are no more await operators required in this particular Click handler: When 
the lUICommond object is assigned a value, the code is running in the user interface thread and a 
dispatcher is not required. 

Prior to await, calling asynchronous operations in C# always seemed to me to violate the 
imperative structure of the language. The owoit operator brings back that imperative structure and 
turns asynchronous calls into what appears to be a series of sequential normal method calls. But de¬ 
spite the ease of owoit, you’ll probably want to keep in mind that a method in which owoit appears is 
actually chopped into pieces behind the scenes with callbacks that you cannot see. 

This can be a problem in some cases. Sometimes when Windows calls a method in your program, 
Windows expects that the method has completed when the method returns control back to the 
operating system. If that method has an owoit operator, that’s not necessarily the case. The method 
with the owoit actually returns control back to Windows prior to the execution of the code following 
the await operator. 

To let Windows know that a method using the await operator hasn’t yet completed, a "deferral" 
object is involved. You’ll see how this works later in this chapter when handling the Suspending event 
of the Application class. 

There are some other restrictions on the owoit operator. If cannot appear in the catch or finally 
clause of an exception handler. However, it can appear in the try clause, and this is precisely how you’ll 
trap errors that occur in the asynchronous method or determine if the asynchronous operation has 
been cancelled (as you’ll see shortly). 

The method in which the owoit operator appears must be flagged as a sync as this Click handler is: 

async void OnButtonCli ck(object sender, RoutedEventArgs args) 

{ 

// … code with await operators 

} 

But this async keyword doesn’t do much of anything. In earlier versions of C#, await was not a 
keyword, so programmers could use the word for variable names or property names or whatever. 
Adding a new await keyword to C# 5.0 would break this code, but restricting await to methods 
flagged with async avoids that problem. The async modifier does not change the signature of the 
method — the method is still a valid Click handler. But you can’t use async (and hence owoit) with 
methods that serve as entry points, specifically Main or class constructors. 
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If you need to call asynchronous methods during page initialization, call these methods in the 
handler for the Loaded event and flag that handler as osync: 

public MainPageO 
{ 

this. InitializeComponentO; 

Loaded += OnLoaded; 

} 

async void OnLoaded(object sender, RoutedEventArgs arg) 

{ 

} 

Or, if you prefer defining the Loaded handler as an anonymous method: 

public MainPageO 
{ 

this. Ini tializeComponentO ； 

Loaded += async (sender, args)=> 

{ 

}； 

} 

See the async before the argument list? 

Cancelling an Asynchronous Operation 

Not all asynchronous operations can be as cleanly structured as the Show Async call of MessageDialog. 
Three characteristics of asynchronous operations often make them more complex: 

■ Cancellation Many asynchronous operations can be cancelled, either by a user deliberately 
stopping an operation that might be taking too long or in some other way. 

■ Progress Some asynchronous operations report progress as they are performing a lengthy 
job. Often users appreciate seeing a progress report, either with a Progress Bor or text. 

■ Errors An asynchronous operation might encounter a problem — for example, trying to open 
a file that no longer exists. 

Let’s tackle the cancellation issue first. Cancelling a message box — that is, removing it from the 
screen prior to the user pressing a button — is not very common, but it might make sense in certain 
scenarios. 

The lAsyndnfo interface — which the four other standard Windows Runtime asynchronous 
interfaces implement — defines a method named Cancel that cancels the operation. As I men¬ 
tioned earlier, the I Async Info interface also includes a Status property that takes on a value of the 
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AsyncStotus enumeration, which has four members: Started, Completed, Canceled, and Error. For the 
last case, IA sync Info also defines an Error Code property of type Exception. 


If you use a callback for the asynchronous operation, generally you need to check this status at the 
top of the callback method and make sure that the status is Completed rather than Canceled or Error 
before calling Get Results. 

If you use await, put the await statement in a try block. If the asynchronous operation is cancelled, 
an exception is thrown of type ToskConceledException. If an actual error occurs in the asynchronous 
operation, the exception indicates that error. 

The HowToAsync3 program called the ShowAsync method of MessageDialog like this: 

IUICommand command = await msgdlg.ShowAsync(); 

You can alternatively break this statement down to reveal the lAsyncOperotion object: 

IAsyncOperation<IUICommand> asyncOp = msgdlg.ShowAsyncC); 

IUICommand command = await asyncOp; 

No difference. This means that you can save the asyncOp object as a field so that some other method 
in the class can call the Cancel method on that object. 

Let’s simulate a cancellation of MessageDialog with a timer. The HowToCancelAsync program 
starts a five-second DispatcherTimer when the MessageDialog is displayed. If the MessageDialog is not 
dismissed in five seconds, the timer Tick callback calls Cancel on the lAsyncOperotion object stored as 
a field: 


Project: HowToCancelAsync | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 
{ 

IAsyncOperation<IUICommand> asyncOp; 

public MainPageO 
{ 

this. InitializeComponent(); 

} 

async void OnButtonCli ck(object sender, RoutedEventArgs args) 

{ 

MessageDialog msgdlg = new MessageDialog ("Choose a color" , "How To Cancel Async") ; 
msgdlg.Commands.Add (new UICommand("Red", null, Colors .Red)); 
msgdlg.Commands.Add (new UICommand("Green", null, Colors .Green)); 
msgdlg.Commands.Add (new UICommand("Bl ue" , null ， Colors. Blue)); 

// Start a five-second timer 
DispatcherTimer timer = new DispatcherTimer() ; 

timer.Interval = TimeSpan .FromSeconds(5); 
timer.Tick += OnTimerTick; 
timer.Start(); 
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// Show the MessageDialog 
asyncOp = msgdlg.ShowAsync(); 
IUICommand command = null; 


try 


command = await asyncOp; 

} 

catch (Exception) 

{ 


} 


// The exception in this case will 


be TaskCanceledException 


// Stop the timer 
timer.StopO; 

// If the operation was cancel 1ed, exit the method 
if (command == null) 
return ; 


// Get the Color value and set the background brush 
Color clr = (Color) command■Id; 

contentGrid.Background = new SolidColorBrush(cl r); 


void OnTimerTi ck(object sender, object args) 
{ 

// Cancel the asynchronous operation 
asyncOp.Cancel(); 



The logic is a little messier than the noncancellable version, of course, but it’s no messier than 
other code involving try and catch blocks, and it still maintains an imperative structure. Once again, 
everything up to the await operator is executed first, and then the method continues in the try block 
when the MessageDialog is dismissed. Either an exception is raised or not, and the program can 
determine if an exception has occurred with a null value of the command variable assigned in the 
try block. 


Approaches to File I/O 

Programmers who work with .NET are familiar with the System. 10 namespace for performing file I/O. 
You can leverage some of this knowledge in Windows 8, but you’ll find the Windows 8 version of 
System. 10 to be a bit emaciated. Instead, much of the Windows Runtime file I/O support can be found 
in several namespaces beginning with Windows.Storage. Be prepared for plenty of new file I/O classes 
and concepts. The whole file and stream interface has been revamped, and any method that accesses 
a disk is asynchronous. 
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A Windows 8 application can take one of three basic approaches to file I/O, which I describe in the 
next three sections in order of preference. 


Application Local Storage 

If an application needs to retain information that is of no value to any other application or to the 
user's examination, it is best to keep this information in application local storage (sometimes called 
isolated storage). This is an area on the hard drive that is private to the application, but the applica¬ 
tion doesn’t need to worry where it’s actually located. If the application is ever uninstalled from the 
machine, the storage is automatically freed. 


Getting access to this storage requires the ApplicationData class in the Windows.Storage 
namespace. An ApplicationData object applicable to the current application can be obtained from the 
static Current property: 

ApplicationData appData = ApplicationData. Current; 

The ApplicationData class defines several properties you can use with this object: 

The LocalSettings and RoomingSettings properties give you access to an ApplicationDotoContoiner 
that provides a dictionary for storing application settings. These application settings are restricted to 
the basic Windows Runtime types (numbers and strings). 

The Local Folder, RoamingFolder, and TemporaryFolder properties return objects of type 
StorogeFolder, an important class also defined in the Windows.Storage namespace. The StorageFolder 
class represents a directory, in this case a directory for private use by the application. The 
StorageFolder class contains methods to create subfolders and to create or access files represented as 
objects of type StorogeFile. A StorageFile object can then be opened and return a stream object for 
reading and writing. 


File Pickers 

The Windows.Storage.Pickers namespace is devoted to the FileOpenPicker, FileSavePicker, and 
FolderPicker. These are the standard dialog boxes that a Windows 8 program can use to open and 
save files in the standard data folders, such as the Documents Library, Music Library, and Pictures 
Library. 


Like MessageDialog, FileOpenPicker and FileSovePicker have asynchronous methods to display 
the dialogs and return information of type StorageFile; the FolderPicker returns an object of type 
StorageFolder. 

Because the user effectively gives the application permission to access the file system by invoking 
one of the pickers and then guides the pickers through the file system, the pickers have a great deal 
of flexibility. However, the application is required to indicate the specific file types that it's interested 
in. When using the FileOpenPicker, for example, the application is required to specify at least one file 
type (such as 〃 .txt〃）in the FileTypeFilter property. These file types cannot include wildcards. 
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A FileOpenPicker will list only the file types specified by the application in the FileTypeFilter 
collection. Although FileOpenPicker can display many different types of files, it cannot list oil possible 
files. 


Bulk Access 

An application can also access the user’s file system directly using the Filelnformation and 
Folderlnformotion classes defined in the Windows.Storage. Bulk Access namespace. The application is 
allowed to query folders for subfolders and files and to manipulate these folders and files in a fairly 
flexible manner. 

However, because this process is not guided by the user, the application needs to declare its needs. 
An application that uses bulk access is required to have a package.appxmanifest file that indicates 
what areas of storage the application is allowed to examine. In Visual Studio you can edit the package, 
appxmanifest file from a dialog box. In the Capabilities section of this dialog, the Documents Library, 
Music Library, Pictures Library, or Videos Library option must be selected to get access to these areas. 
These capabilities define the limitations of the application. For the Documents Library, the Declara¬ 
tions section must include File Type Associations, and all the file types that the application wants must 
be explicitly listed; all file queries are limited to these file types. 

Ill demonstrate the use of the bulk access classes with the Pictures Library in the PhotoScatter pro¬ 
gram in Chapter 14, "Bitmaps.” The other two approaches to file I/O are demonstrated in this chapter. 


File Pickers and File I/O 


Let's become familiar with the FileOpenPicker and FileSavePicker classes by writing a simple program 
called PrimitivePad similar to the classic Windows Notepad. This program is basically a big TextBox 
with a couple commands. Normally these commands would be implemented on an application bar, 
but I’m going to save that topic for Chapter 8, "App Bars and Popups.” 

PrimitivePad has just two buttons for file I/O: Open and Save As. If it were a real application, it 
would also have New and Save buttons and it would prompt you to save a file if you pressed New or 
Open without saving your previous work. That logic is also coming up in the next chapter. 

PrimitivePad has a third button for the word-wrapping mode, which is saved as a program setting. 
Here’s the XAML file: 


Project: PrimitivePad I File: MainPage.xaml (excerpt) 

<Page … > 

<Page.Resources 〉 

<Style x : Key="buttonStyl e" TargetType="ButtonBase"> 

〈Setter Property="Hori zontalA1ignment" Val ue="Center" /> 
〈Setter Property="Margi n" Val ue="0 12" /> 

</Style> 

</Page.Resources 〉 
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<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Grid.RowDefinitions> 

<RowDefinition Hei ght="Auto" /> 

< RowDefinition Height:"*" /> 

</Grid.RowDefiniti ons> 


<Grid.ColumnDefinitions> 

<ColumnDefinition Width="*" /> 

<ColumnDefinition Width="*" /> 

<Co1umnDefinition Width="*" /> 

</Crid.ColumnDefinitions> 

<Button Content="Open ..." 

Grid.Row="0" 

Grid.Col umn="0" 

Styl e="{StaticResource buttonStyl e}" 

Cli ck="OnFi 1eOpenButtonCli ck" /> 

<Button Content="Save As" 

Grid.Row="0" 

Grid.Col umn="l" 

Styl e="{StaticResource buttonStyl e}" 

Cli ck="OnFi 1eSaveAsButtonClick" /> 

<ToggleButton Name="wrapButton" 

Content="No Wrap" 

Gn'd.Row="0" 

Grid.Col umn="2" 

Styl e="{StaticResource buttonStyl e}" 
Checked="OnWrapButtonChecked" 
Unchecked="OnWrapButtonChecked" /> 

<TextBox Name="txtbox" 

Grid.Row= ,, l" 

Grid.Col umn="0" 

Grid.ColumnSpan="3" 

FontSize="24" 

AcceptsReturn="True" /> 

</Gri d> 

</Page> 
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The three buttons are displayed at the top, and in the big TextBox you can perhaps type some 
poetry: 



"Hope" is the thing with feathers — 

That perches in the soul — 

And sings the tune without the words — 
And never stops — at all — 

And sweetest — in the Gale — is heard — 
And sore must be the storm — 

That could abash the little Bird 
That kept so many warm — 

I’ve heard it in the chillest land — 

And on the strangest Sea — 

Yet, never, in Extremity, 

It asked a crumb — of Me. 


The FileOpenPicker and FileSovePicker classes invoke dialogs that take over the screen from your 
application and don’t return control until they have been dismissed. If this is unacceptable to you, 
you’ll want to explore the bulk access approach and navigate the directories on your own. 

Both classes deliver an object of type StorogeFile back to your application. [FileOpenPicker has an 
option for multiple selection that returns multiple StorageFile objects.) StorogeFile is defined in the 
Windows.Storage namespace and represents an unopened file. Calling one of the Open methods on 
this StorogeFile object gives you a stream object in the form of an interface such as IlnputStream or 
IRandomAccessStreom defined in the Windows.Storage.Streams namespace. You can then attach a 
Data Reader or Da to Writer object to this stream for reading or writing. Through extension methods 
defined in System. 10, it’s also possible to create a .NET Stream object from the Windows Runtime 
stream objects and then use some familiar .NET objects, such as StreomReader or Stream Writer, for 
dealing with files. You might be able to salvage some existing code that uses .NET streams, and youll 
also need these .NET stream objects for reading and writing XML files. 

The only prerequisite for invoking FileOpenPicker is adding at least one string to the FileTypeFilter 
collection (for example, 〃 .txt〃). You then call the PickSingleFileAsync method. The standard file open 
picker is displayed, and the user selects an existing file and then presses Open or Cancel. If you use 
await with this method call, your program then gets back a StorogeFile object indicating the file that 
the user selected. Here’s the entire Click handler for the Open button: 


Project: PrimitivePad I File: MainPage.xaml.es (excerpt) 

async void OnFi1eOpenButtonCli ck(obj ect sender, RoutedEventArgs args) 
{ 

FileOpenPicker picker = new Fi1eOpenPi cker(); 

picker.FileTypeFiIter.Add(" . txt") ; 

StorageFile StorageFile = await picker.PickSingleFileAsyncC); 
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// If user presses Cancel, result is null 
if (storageFi1e == null) 
return ; 

using (IRandomAccessStream stream = await storageFi 1 e.OpenReadAsyncO) 
{ 

using (DataReader dataReader = new DataReader (stream)) 

{ 

uint length = (uint) stream.Size; 

await dataReader.LoadAsync(length); 

txtbox.Text = dataReader.ReadString(length); 

} 



PickSingleFileAsync actually returns an IAsyncOperotion<StorageFile> object, but this is one of the 
few asynchronous calls in which the object represented by the generic argument can be null. This null 
value occurs when the user presses the Cancel button on the file open picker. For this case, nothing 
more needs to be done. 

To open that StorogeFile object for reading, you can call OpenReadAsync on it. That’s 
another asynchronous operation, which of course makes sense because the call must access the 
disk. OpenReadAsync actually returns an object of type (hold your breath) 
IAsyncOperotion<IRandomAccessStreomWithContentType> l but the 

IRondomAccessStreamWithContentType interface implements IRondomAccessStreom, so I’ve used 
the shorter version. IRandomAccessStream implements /Disposable, so it’s a good idea to put the 
stream object in a using block to be automatically disposed. 

DataReader also implements /Disposable. This class provides access to many Read methods for the 
Windows Runtime primitive types, such as ReadString. These Read methods are not asynchronous 
because they don’t involve disk accesses. The methods merely read bytes from an internal buffer (of 
type /Buffer) stored in memory and converts them to specific data types. The method call that actu¬ 
ally accesses the disk file is LoadAsync, which loads a particular number of bytes from the file into this 
buffer and which must occur before any Read calls. For very large files, you might want to break down 
the file loading into smaller pieces. DataReader has an UnconsumedBufferLength property to help 
with this process. 

Without the await operator, these three asynchronous methods would all require their own 
callbacks and a fourth callback would be required to run the code that sets the Text property of the 
Text Box in the user interface thread. 

The file-saving logic is similar: 

Project: PrimitivePad I File: MainPage.xaml.es (excerpt) 

async void OnFi1eSaveAsButtonCli ck(obj ect sender, RoutedEventArgs args) 

{ 

Fi1eSavePicker picker = new Fi1eSavePi cker(); 

picker.DefaultFi1eExtension = ".txt" ; 

picker.FileTypeChoices.Add ("Text" , new Li st<stri ng> { ".txt" }); 
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StorageFi 1 e storageFi 1 e = await picker.PickSaveFileAsync(); 


// If user presses Cancel, result is null 
if (storageFile == null) 
return ; 

using (IRandomAccessStream stream = await storageFi1e.OpenAsync(Fi 1eAccessMode .ReadWrite)) 
{ 

using (DataWriter dataWriter = new DataWriter (stream)) 

{ 

dataWriter.WriteString(txtbox.Text); 
await dataWriter.StoreAsync(); 

} 



The StoreAsync method of Da to Writer returns a DatoWriteStoreOperotion object that implements 
I A syn cOper a tion < uin t>. This uint indicates the number of bytes stored in the file. This value isn’t 
used for anything here, and Store Async is the last statement of this method, so you might wonder if 
you need to use the await operator on this call. In general, you can call asynchronous methods that 
don’t return values without the await operator, but keep in mind that the method making the call will 
continue execution while the asynchronous method runs, and that might be an issue if the method 
making the call implicitly expects the asynchronous method to complete before continuing execu¬ 
tion. In this particular case, I’d be leery of omitting await because the using blocks implicitly close the 
DotoWriter and IRandomAccessStream objects and you don’t want that happening before Store Async 
completes. 

The PrimitivePad program also gives you the option to set text wrapping on and off using a 
ToggleButton. The only part of the MoinPoge code-behind file you haven't seen yet is the portion of 
the program that is devoted to that feature: 


Project: PrimitivePad | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 
{ 

ApplicationDataContainer appData = ApplicationData. Current.LocalSettings; 

public MainPageO 
{ 

this .Ini ti alizeComponent(); 

Loaded += (sender, args)=> 

{ 

if (appData.Values.Contai nsKey("TextWrapping")) 

txtbox.TextWrapping = (TextWrappi ng)appData.Values ["TextWrapping"] ; 


wrapButton.IsChecked = txtbox.TextWrapping == TextWrapping .Wrap; 
wrapButton.Content = (bool)wrapButton.IsChecked ? "Wrap" : "No Wrap" ; 


}； 


txtbox. Focus(FocusState. Programmatic); 
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void OnWrapButtonChecked (object sender, RoutedEventArgs args) 


txtbox.TextWrapping = (bool)wrapButton.IsChecked ? TextWrapping .Wrap : 


TextWrapping .NoWrap; 


wrapButton.Content = (bool)wrapButton .IsChecked ? "Wrap" : "No Wrap"; 
appData.Values ["TextWrappi ng"] = (int)txtbox .TextWrapping; 


A field obtains an ApplicationDotaContainer object for this application. The Values property of 
this object is a dictionary that an application can use for saving program settings — at least those 
that can be expressed as primitive types. During the Loaded handler, if this dictionary contains a 
"Textwrapping" item, that item is used to set the property of the TextBox, and the ToggleButton is 
initialized accordingly. 

Whenever the ToggleButton is checked or unchecked, the handler sets the TextWropping property 
of the TextBox and saves the new value in the dictionary. 

This is one way to save application settings. Ill show you another way later in this chapter involving 
the Suspending property of the Application class. If you ever need to locate these settings (and other 
local storage) on the hard drive, first use Visual Studio to check the Package Name of the application 
in the Packaging tab of the Package.appxmanifest file. (Or check the Name attribute of the Identity 
element in the actual file.) This is a GUID that uniquely identifies the application. The settings and 
local data can be found at the directory: 

C:\Users\[user-name]\AppData\Local\Packages\[app-guid] 


Handling Exceptions 


If you work at it, you can crash the PrimitivePad program. For example, press the Open button in 
PrimitivePad, select a file in the picker, but before pressing the picker’s Open button, use Windows 
Explorer (or something else) to delete the selected file. When PrimitivePad tries to open that 
nonexistent file, an exception is raised. 

To catch errors such as these, the entire block of code after the check for a null Storage File can be 
put in a try block. But watch out: You can’t display a MessogeDialog informing the user of the prob¬ 
lem in the catch block because await isn’t allowed in a catch block. A better way to handle exceptions 
looks more like this: 

async void OnFi1eOpenButtonCli ck(object sender, RoutedEventArgs args) 

{ 

Exception exception = null; 



using (IRandomAccessStream stream = await storageFile.OpenReadAsyncO) 
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using (DataReader dataReader = new DataReader (stream)) 
{ 

uint length = (uint) stream.Size; 
await dataReader.LoadAsync(length); 
txtbox.Text = dataReader.ReadString(length); 



catch (Exception exc) 
{ 

exception = exc; 

} 


} 


if (exception != null) 

{ 

MessageDialog msgdlg = new MessageDialog (except!on.Message, 

•■File Read Error") ; 


await msgdlg.ShowAsyncC); 

} 


The final //statement determines if an exception has occurred by checking for a non-null value of the 
exception variable. At that point a MessageDialog can be used to display the error. 


Consolidating Async Calls 


Suppose you’d like to consolidate all the file-open and file-save logic into methods that are then 
called from the Click handlers of the buttons. This might be warranted if you're invoking these open 
and save pickers from more than one place in the program. 

Let’s imagine a method named Load File that displays the FileOpenPicker, reads the entire contents 
of a text file, and returns a string. The OnFileOpenButtonClick method can then be as simple as this: 

void OnFi1eOpenButtonCli ck(object sender, RoutedEventArgs args) 

{ 

txtbox.Text = LoadFileC); 

} 

Well, no, it actually can’t be as simple as that. This Load File method cannot return a string because 
that string isn’t available until multiple asynchronous operations have completed. Keep in mind that 
the await operator actually results in the creation of callback methods just as if you wrote them 
explicitly. Try writing a LoadFile method with explicit callback methods and then try to return a string 
from Load File. You can’t do it. 

You must be able to apply an await operator to LoadFile itself, which means you probably want to 
name it LoodFileAsync, which you’ll call like this: 

async void OnFi1eOpenButtonCli ck(object sender, RoutedEventArgs args) 


} 


txtbox.Text = await LoadFi1eAsync(); 
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But this should actually make you happy because it means that you can write LoadFileAsync 
without any exception handling and instead put the exception handling in the caller, in this case the 
OnFileOpenButtonClick handler. 

But the real question is this: What should the return type of LoadFileAsync be? Judging 
from the asynchronous methods implemented in the Windows Runtime, you might guess 
I A syn cOp era tion < string >, but that’s not so. The big problem is that the Windows Runtime does not 
define a public class that implements this interface. 

Instead, as a C# programmer, you'll use classes in .NET that support asynchronous operations. The 
best return value of LoadFileAsync is Task<string>, and the method looks like this: 


async Task<stri ng> LoadFi 1 eAsyncO 
{ 

Fi1eOpenPicker picker = new Fi1eOpenPi cker() ; 

picker.FileTypeFiIter.Add (" .txt") ; 

StorageFi 1 e storageFile = await pi cker. Pi ckSi ngl eFi 1 eAsyncO ; 

//If user presses Cancel, result is null 
if (storageFile == null) 
return null; 

using (IRandomAccessStream stream = await StorageFi 1 e.OpenReadAsyncO) 
{ 

using (DataReader dataReader = new DataReader (stream)) 

{ 

uint length = (uint) stream.Size; 
await dataReader.LoadAsync(length); 
return dataReader.ReadString(length); 



Although this method is named LoadFileAsync, all the code that you supply to this method runs 
in the user interface thread. But it’s considered an asynchronous method because parts of it run 
in secondary threads. Notice that the method returns null if the user presses Cancel on the picker. 

You can’t assign a null to the Text property of TextBox, so the Click handler must accommodate that 
possibility: 

async void OnFi1eOpenButtonCli ck(object sender, RoutedEventArgs args) 

{ 

string text = await LoadFi 1 eAsyncO ； 

if (text != null) 

txtbox.Text = text; 

} 

What is Task? Task is a class defined in the System .Threading .Tasks namespace, and it is the core of 
the .NET support of asynchronous and parallel processing. It exists in both generic and nongeneric 
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versions. You’ll use the nongeneric version for a method that doesn’t return anything, such as a 
method that consolidates all the save logic: 

async void OnFi1eSaveAsButtonCli ck(obj ect sender, RoutedEventArgs args) 

{ 

await SaveFileAsync(txtbox.Text); 

} 

async Task SaveFi1eAsync(stri ng text) 

{ 

Fi1eSavePicker picker = new Fi1eSavePi cker(); 

picker.DefaultFi1eExtension = ".txt" ; 

picker.FileTypeChoices. Add("Text" , new Li st<string> { ".txt" }); 

StorageFi1e storageFi1e = await picker.PickSaveFileAsync(); 

// If user presses Cancel, result is null 
if (storageFi1e == null) 
return ; 

using (IRandomAccessStream stream = await storageFi1e.OpenAsync(Fi 1eAccessMode .ReadWrite)) 
{ 

using (DataWriter dataWriter = new DataWri ter(stream)) 

{ 

dataWriter.WriteStri ng(text); 
await dataWriter.StoreAsync(); 



Support of asynchronous processing in .NET and the Windows Runtime is similar enough that 
the types can be converted to each other. Task has an extension method named AsAsyncAction 
that returns an lAsyncAction, and Task<T> has an extension method AsAsyncOperation<T> that 
returns an IA syn cOperation <T>. Similarly, I Async Action has an AsTosk method that returns a Task, and 
I A syn cOper a tion <T> has an AsTosk<T> method that returns a Task<T>. 

However, Task is much more powerful than the asynchronous support in the Windows Runtime, 
offering facilities to manage parallel processing and to await groups of tasks. Task really deserves a 
book of its own — this is not that book, but later in this chapter 111 show you how to use Task for your 
own lengthy processing jobs. 

Streamlined File I/O 


Although it’s good for programmers to be familiar with file I/O using the Data Reader and DataWriter 
classes, much of your file I/O jobs can probably be accomplished with some streamlined methods. 
These are available in the static FilelO and PathIO classes from the Win do ws. 5 torag e namespace. 
Methods in these classes read or write whole files in single asynchronous calls. 

For text files, the FilelO. Read LinesAsync method can read a text file and return an I List of 
string objects (one per line) and FilelO.ReadTextAsync can return a file in a single string object. In 


CHAPTER 7 Asynchronicity 


243 



PrimitivePad, the block of two nested using statements in OnFileOpen Button Click can be replaced 
with this: 

txtbox.Text = await Fi1elO .ReadTextAsync(storageFi1e); 

Similarly, the file save logic can be replaced with this single call: 

await Fi1 elO.Wri teTextAsync(storageFi1e, txtbox.Text, UnicodeEncoding .Utf8); 

For binary files, you can use ReadBufferAsync and WriteBufferAsync. These methods work with an 
object of type I Buffer. An /Buffer object is basically an array of bytes that exists in system memory. 
References to an I Buffer are tracked so that Windows can remove it from memory if it’s no longer 
needed. 

The I Buffer object can’t be accessed directly from a C# program, but you can get at it indirectly. To 
create a binary file, you can create a Data Wri ter object, write into it, and then save the internal I Buffer 
object that the Da to Writer created: 

DataWriter dataWriter = new DataWri ter() ; 

II... write to dataWriter 

await Fi 1 elO.Wri teBufferAsync(storageFi 1 e, dataWriter.DetachBufferO); 

For reading a binary file, you first obtain an I Buffer object by reading the file and then create a 
DataReoder from that: 

IBuffer buffer = await Fi1 elO. ReadBufferAsync(storageFi1e); 

DataReader dataReader = DataReader. FromBuffer(buffer); 

II... read from dataReader 

If you include the System.Runtime.InteropServices.WindowsRuntime namespace in your program, you 
can convert an IBuffer object to a .NET Stream object and then use this Stream to create other classes 
defined in the System. 10 namespace: BinaryReoder, Bin ary Writer, StreamReader, and StreamWriter. Or 
you can convert an IBuffer to an array of bytes. 

The Path 10 class is similar to FilelO but instead of passing StorogeFile objects to the static methods, 
you pass a string URL This URI generally begins with 〃 ms-appx:///" to access files stored as program 
content and 〃 ms-appdata:///’’ to access files in application storage, as I’ll demonstrate shortly. 

The Http Client class is the main class for uploading or downloading files over the Web, but if you 
don’t need that flexibility, RandomAccessStreomReference comes in very handy: 

Uri uri = new Uri ("http ://... ； 

RandomAccessStreamReference streamRef = RandomAccessStreamReference .CreateFromllri(uri); 


using (IRandomAccessStream stream = await streamRef.OpenReadAsyncO) 
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You can then call ReodAsync on that IRondomAccessStreom to read the contents of the file into an 
I Buffer, and then pass the /Buffer to the static Data Reader. From Buffer method. 


Application Lifecycle Issues 


The PrimitivePad program has a subtle flaw that needs to be addressed. As you know, if you run 
the regular Windows desktop Notepad program, type in some text, and then try to terminate the 
program — by pressing the Close button at the upper right corner, by pressing Alt+F4, by selecting 
Exit from the File menu, or by shutting down Windows — Notepad will display a "Do you want to save 
changes".?” message box. You can select Save, Don’t Save, or Cancel. 

We’re all familiar with this convention, but it is no longer a good solution. Computing no longer 
exclusively involves sitting down at your desk, turning on the computer, doing some work, and then 
shutting the computer down. It’s just as likely that you'll pull a tablet out of your handbag or off the 
coffee table, unlock the screen, spend some time with it, and then toss it back where it came from, 
perhaps putting it to sleep by pressing the on/off button or letting it go to sleep by itself. 

Do you want your Windows applications to ask you to save data when the computer is going to 
sleep? No, you do not. By putting the computer to sleep (or even by turning your eyes away from the 
screen) you’ve signaled that continued interaction with the computer is precisely what you do not 
want. 

But here’s the problem: What if that tablet now sitting on the coffee table determines that the 
battery is getting too low to continue maintaining even the sleep state and it decides to turn itself 
off? In a practical sense, it can’t warn you that this is happening. 

Or perhaps you're using the computer and Windows needs to free up some memory. One way 
it can do this is by terminating applications that haven't been used in a while. Again, as a user, you 
probably don’t want to be notified of this event. 

For these reasons, a polite Windows 8 application saves information so that it can provide a 
continuous user experience regardless of whether it’s terminated or not. If an application contains 
some unsaved data that the user might regret losing and that application is terminated, then the next 
time that application runs, it should display that data. (Obviously, for some applications this is more 
important than for others. For a calculator, for example, it probably doesn’t matter all that much if the 
program discards the data. But for a spreadsheet it’s a very big deal.) 

This is easy, right? As a programmer all you need to know about is the event that is fired when 
the application is about to be terminated. You can use this event to save any unsaved data in local 
application storage and then restore that data the next time the program is run. 

The only problem is: There’s no such event. 
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However, there is an event that indicates when an application is being suspended. An application 
is always suspended before it’s terminated (unless the termination is abnormal, such as crash), but a 
suspension doesn’t necessarily result in termination. There’s another event that indicates when the 
application is being resumed following a suspension. 

An application is suspended when it’s no longer running in the foreground — that is, when you 
bring up the Windows start screen or sweep your finger from the left edge to bring another program 
to the foreground. An application is also suspended when you press Alt+F4 to terminate it or when 
you put the computer to sleep. In all these cases, there’s actually about a 10-second delay before the 
application is suspended; this delay is for Windows (and the application) to avoid doing work if the 
program is resumed shortly. 


After a program is suspended, it might be resumed or it might be terminated. Much time might 
elapse after suspension before resumption or termination. Because there is no event to indicate when 
a program is being terminated, the application must use the suspension to save everything it needs 
to resume, even though that suspension might not end in a termination. (Now perhaps you can see 
why there’s no specific event for program termination: If the program is already suspended, Windows 
would need to resume the application just to fire the termination event!) 

The Application class defines two events for this purpose: Suspending and Resuming. The 
Suspending event is much more important than Resuming. An application uses this event to save 
unsaved data in local application storage. The program does not need to restore this data during the 
Resuming event. Windows restores the application itself. All the program needs to do is load the data 
the next time it’s run. 

However, an application can choose to do other chores during the Suspending event and undo 
those during the Resuming event. For example, the program can try to minimize its footprint in 
memory by letting go of large resources that it can re-create. Or it might use the Resuming event to 
refresh itself with updated data coming from a Web source. 

When a program is running under the Visual Studio debugger, it does not get suspended and 
resumed the same way as when it’s running by itself. An application running by itself is suspended 
when the program is no longer running in the foreground, but an application running under the 
Visual Studio debugger is not 


Another difference: A program is not suspended prior to termination if the termination is 
abnormal. Abnormal termination can occur by an unhandled exception or — keep this in mind when 
you’re experimenting — when you use the Stop Debugging command of Visual Studio. 

However, if you terminate an application running under the Visual Studio debugger with Alt+F4, 
the program gets a Suspending event and the program is terminated, but that process is delayed 
about 10 seconds, during which time Visual Studio still believes that the program is running! 

To compensate for these issues, Visual Studio has commands on the Debug Location toolbar to 
manually Suspend, Resume, or Suspend And Shutdown an application. These commands are essential 
for developing suspension and resumption code while running the program under the debugger. 
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Because it’s hard to examine normal Suspending and Resuming events while a program is running 
under Visual Studio, I’ve written a little program that logs these events to a file that it stores in local 
application storage. This program is intended to be run outside the Visual Studio debugger. 

The XAML file of the SuspendResumeLog program contains a read-only TextBox: 


Project: SuspendResumeLog | File: MainPage.xaml (excerpt) 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<TextBox Name="txtbox" 

AcceptsRet urn="True” 

IsReadOnly="True" /> 

</Grid> 


The code-behind file handles three events: the Loaded event of Main Page (which is executed once 
when the program is launched), and the Suspending and Resuming events of the current Application 
object. All these events are logged to a file named logfile.txt that is saved in local application storage: 

Project: SuspendResumeLog | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

StorageFile logfi1e; 

public MainPageO 

{ 

this. Ini tializeComponent(); 

Loaded += OnLoaded; 

Application .Current.Suspend!ng += OnAppSuspending; 

Application ■Current■Resuming += OnAppResuming; 

} 


async void OnLoaded(object sender, RoutedEventArgs args) 

{ 

// Create or obtain the log file 

StorageFolder local Folder = Appli cationData.Current.Local Folder; 
logfi le = await local Folder.CreateFileAsyncClogfile.txt", 

Creati onCol1isionOption. OpenlfExists); 

// Load the file and display it 

txtbox.Text = await Fi1elO .ReadTextAsync(1ogfi1e); 

// Log the launch 

txtbox.Text += String . Format("Launchi ng at {0}\r\n" , DateTime.Now.ToStn'ngO); 
await Fi1elO .WriteTextAsync(1ogfi1e, txtbox.Text); 

} 

async void OnAppSuspendi ngCobject sender, SuspendingEventArgs args) 

{ 

SuspendingDeferral deferral = args.SuspendingOperation.GetDeferral(); 
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// Log the suspension 

txtbox.Text += Stri ng . FormatC'Suspendi ng at {0}\r\n" , DateTime.Now.ToStringO); 
await Fi leIO.WriteTextAsync(logfile, txtbox.Text); 


deferral.Complete(); 

} 

async void OnAppResuming (object sender, object args) 

{ 

// Log the resumption 

txtbox.Text += Stri ng. Format("Resumi ng at {0}\r\n" , DateTime.Now.ToStringO); 
await Fi 1 elO. WriteTextAsync(1ogfi1e, txtbox.Text); 



During the Loaded event, the program obtains the StorageFolder associated with local storage for 
this application and creates a file named logfile.txt. Using the handy Creation Collision Option 
•OpenlfExists argument, this CreateFileAsync call is the same as a GetFileAsync if the file already exists, 
which it will the second and subsequent times this program is run. 

The OpenlfExists enumeration member is somewhat misnamed. It should really be GetlfExists 
because the file is not opened for reading and writing in the normal sense. However, the file is created 
with a zero-byte length, and a reference to that file is obtained. The FilelO.ReodTextAsync and FilelO 
.WriteTextAsync calls actually open the file, read or write to it, and close the file. 

Notice the use of the SuspendingDeferral object in the Suspending event handler. Without that, 
Windows would think that the Suspending handler had completed when it calls the WriteTextAsync 
call because that’s when the handler is exited for the first time. 

Normally, when a program maintains unsaved data in local storage, the program only needs to 
load the data during the Loaded event (or some other initialization event) and save it during the 
Suspending event. The SuspendResumeLog program also saves the file during the Loaded event and 
Resuming event. Although the program is most designed to run outside the Visual Studio debugger, 

I added this code in case the program is running under the Visual Studio debugger and terminates 
with Stop Debugging. Without those saves, that data would be lost because the Suspending handler is 
not fired for this type of termination. 

When testing a program’s ability to save and restore data running in the Visual Studio debugger, it 
might be best to get into the habit of terminating the program by using the Suspend And Shutdown 
command rather than Stop Debugging. 

You can replace the FilelO.ReadTextAsync call with this: 
txtbox.Text = await PathIO .ReadTextAsync( "ms-appdata : ///local/Iogfi1e.txt") ; 

And you can replace the FilelO.WriteTextAsync calls with this: 

await PathIO .WriteTextAsync ("ms-appdata : ///local/Iogfi1e.txt" , txtbox.Text); 


248 PART Elementals 


The ms-appdata prefix indicates application isolated storage. What appears to be a directory named 
local actually differentiates this area from rooming or temp. Even if you use these file URIs for reading 
and writing, you still need to create the StorageFile object by using a method of StorogeFolder. 

Normally, code that updates log files appends text to an existing file. There are methods in FilelO 
and PathIO for appending text, but I decided not to do that in the SuspendResumeLog program 
because the same text would need to be appended to both the TextBox and the log file, or the 
Text Box would need to be reloaded from the appended log file. 

The QuickNotes project is similar to SuspendResumeLog in that it consists of a TextBox and saves 
the contents in local application storage. However, QuickNotes lets you type text in the TextBox, and 
of course it’s automatically saved for the next time you bring up the program. Here’s the XAML file: 


Project: QuickNotes | File: MainPage.xaml (excerpt) 

<Grid Background:" {StaticResource ApplicationPageBackgroundThemeBrush}"> 
<TextBox Name="txtbox" 

AcceptsReturn="True" 

TextWrappi ng="Wrap" /> 

</Grid> 


The code-behind file uses FilelO.ReodTextAsync to read the file (because it already has a 
StorageFile object handy) but Path I O.WriteTextAsync for writing the file: 


Project: QuickNotes | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

public MainPageO 

{ 

this .Ini tializeComponent(); 

Loaded += OnLoaded; 

Application .Current.Suspending += OnAppSuspending; 

} 

async void OnLoaded(object sender, RoutedEventArgs args) 

{ 

StorageFol der local Folder = Appli cationData.Current.Local Folder; 

StorageFile StorageFile = await localFolder.CreateFi1eAsync ("QuickNotes.txt" , 

CreationCol1isionOption .OpenlfExists); 
txtbox.Text = await Fi1elO. ReadTextAsync(storageFile); 
txtbox.SelectionStart = txtbox.Text.Length; 
txtbox.Focus (Focus State .Programmati c); 


async void OnAppSuspendi ng(object sender, SuspendingEventArgs args) 

{ 

SuspendingDeferral deferral = args.SuspendingOperation.GetDeferral(); 

await PathIO. WriteTextAsync ("ms-appdata:///local/QuickNotes.txt" , txtbox.Text); 

deferral.Complete(); 
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Your Own Asynchronous Methods 


Earlier I demonstrated how to write a method with the word Async at the end that calls one or 
more other asynchronous methods. The code that you supply for such a method runs in the user 
interface thread, even though the asynchronous methods that are called within that method run in 
secondary threads. 

Sometimes an application needs to perform a lengthy computational job that has the potential 
of grinding the Ul thread to a halt. If you can chop the job into tiny pieces, you might be able to use 
a DispatcherTimer ora CompositionTorget. Rendering event to do it. The event handlers run in the Ul 
thread, but the job is spread out in such a way that the user interface remains responsive. 

Or you can do the job in a secondary thread. One approach is to make use of the ThreadPool class 
in the Windows.System.Threading namespace, but the Task class is much more versatile, so that’s the 
approach 111 be demonstrating here. 

The simplest Task.Run method has an argument of type Action (a method with no arguments and 
no return value) and runs that argument in a thread obtained from the thread pool. Generally, you’ll 
use a lambda function for this argument. 

For example, suppose you have a method (perhaps with a couple arguments) that requires a long 
time to run: 

void Bi gJob(object argl, object arg2) 

{ 

// … heavy processing job 

} 

You don’t want to run this method directly from the user interface thread, but you can await this 
method by putting it in the body of a lambda function that you pass to Task.Run: 

await Task.Run(() => BigDob("abc", 555)); 

Because Task. Run runs Big Job in a secondary thread, BigJob cannot contain any code that accesses 
user interface objects. (Or rather, if it does need to contain code that accesses user interface objects, 
it must do so using the Run Async method of CoreDispotcher. If BigJob needs to await that Run Async 
call, BigJob must be declared as async and return a Task object.) 

Here’s another method that requires lots of processing time but returns a value: 

double CalculateMagi cNumber(stri ng str, double x) 

{ 

double magicNumber = 0; 

// … big job 
return magicNumber; 

} 
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Again, you don’t want to call this method on the user interface thread, but you can do so safely 
with Task. Run: 

double magicNum = await Task. Run(()=> 

{ 

return CalculateMagicNumber("abc", 5); 

}); 

Because the method in the body of the lambda function passed to Task.Run returns a double (the 
return value from CalculateMogicNumber), the return value of Task.Run is Tosk<double>. Notice the 
await operator that returns the double value that ColculoteMogicNumber calculated. 

Or you can define a ColculoteMagicNumberAsync method like so: 


Task<double> CalculateMagicNumberAsync(stri ng str, double x) 

{ 

return Task. Run(()=> 

{ 

return CalculateMagicNumber(str, x); 

}); 

} 

You can then call this method from the user interface thread: 

double magicNum = await CalculateMagicNumberAsync("xyz", 333); 

Or you can consolidate the entire big job in a single method: 

Task<double> CalculateMagicNumberAsync(stri ng str, double x) 

{ 

return Task. Run(()=> 

{ 

double magicNumber = 0; 

// … big job in non-UI thread 
return magicNumber; 

}); 

} 

If the calculation requires some calls to other asynchronous methods, those methods should be 
preceded with await and the lambda function should be declared with osync: 


Tasl«double> CalculateMagi cNumberAsync(stri ng str, double x) 
{ 

return Task. Run(async ()=> 

{ 

double magicNumber = 0; 

// … big job with await’s 


return magicNumber; 


}); 
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This last form — with everything in this one method — is the easiest if you want to incorporate 
cancellation and progress reports. 

It is very likely that the asynchronous method that you’re defining contains some kind of loop: 


Tasl«double> CalculateMagi cNumberAsync(stri ng str, double x) 
{ 

return Task. Run(async ()=> 

{ 

double magicNumber = 0; 

for (int i = 0; i < 100; i++) 

{ 

// … big job with await’s 

} 

return magicNumber; 

}); 

} 


This loop is a good place to perform both cancellation and progress, but some judgment and 
prudence are required. You don’t want to check for cancellation or report progress thousands of 
times per second, or every five seconds. Every second or several times a second is about right. For a 
loop that executes thousands or millions of times, you might want to include some logic that checks 
for cancellation or reports progress only if the loop variable is equally divisible by 100, for example. 

To incorporate cancellation into this method, you add a method parameter of type 
CancellotionToken and at a convenient point, call the ThrowlfCcmcellationRequested method on that 
argument: 

Tasl«double> CalculateMagi cNumberAsync(stri ng str, double x, 

Cancel 1ationToken cancel 1ationToken) 

{ 

return Task. Run(async ()=> 

{ 

double magicNumber = 0; 

for (int i = 0; i < 100; i++) 

{ 

cancel 1ationToken.Th rowlfCancel1ationRequestedO; 

// … big job with await’s 

} 

return magicNumber; 

}, cancel 1ationToken); 

} 


Notice that the can cel I ati on Token parameter is also passed as a second argument to Task. Run. This 
allows the task to be cancelled before it’s even started. 
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Now, when calling the ColculoteMogicNumberAsync method, you must pass a CancellationToken 
as the last argument. To obtain this object, you’ll need to define an object of type 
ConcellotionTokenSource as a field: 

Cancel 1ationTokenSource cts; 

This object must be defined as a field because it needs to be accessed from a method that triggers 
the cancellation, very likely based on the user’s initiative: 


void OnCancelButtonCli ck(object sender, RoutedEventArgs args) 
{ 

cts.Cancel(); 

} 


Prior to calling CalculateMagicNumberAsync, a new CancellationTokenSource must be created and 
its Token property passed to the method in a try block: 

cts = new Cancel 1ationTokenSource() ; 

double magicNum = 0; 

try 

magicNum = await CalculateMagicNumberAsync("xyz", 333, cts.Token); 

} 

catch (OperationCanceledException) 

{ 

// … cancellation logic 

} 

catch (Exception exc) 

{ 

// … other exceptions "logic 

} 

When the Cancel method of ConcellotionTokenSource is called, the next time the asynchronous 
method calls the ThrowlfConcellotionRequested method of the CancellationToken object, an exception 
is raised of type OperationCanceledException, and this is caught by the code calling the asynchronous 
method. Other exceptions that might be raised (most likely as a result of file I/O or web access calls) 
are trapped in the second catch block. 

If you want the asynchronous method to report progress, you add another parameter to the 
method for that purpose. This parameter is of type IProgress<T>, where T is the type you prefer for 
marking the progress. Generally T will be a double, but whether the progress ranges from 0 to 1 or 0 
to 100 is up to you. If the latter, T can be an int. I’ve even seen an example where 7" is a bool, with true 
indicating the job is complete! 

At a convenient place — perhaps at the same point you check for cancellation — you can report 
progress: 

Tasl«doubl e> CalculateMagicNumberAsync(stri ng str, double x, 

Cancel 1ationToken cancel 1ationToken, 

IProgress<doubl e> progress) 
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return Task. Run(async ()=> 

{ 

double magicNumber = 0; 

for (int i = 0; i < 100; i++) 

{ 

cancel 1ationToken.ThrowlfCancel1ationRequestedO; 
progress.Report ((double) i); 


// … big job with await’s 

} 

return magicNumber; 

}，cancel 1ationToken); 

} 


This code just casts the loop variable to a double so it ranges from 0 to 100 and represents a 
percentage (which makes it convenient for setting the Value property of a ProgressBor). In some cases 
you might want to explicitly report a zero progress at the beginning of the method and a maximum 
progress at the end. 

You’ll also want a method that has the progress type you’ve selected as a parameter and which 
displays that progress: 

void ProgressCal1 back(doubl e progress) 

{ 

progressBar.Value = progress; 

} 

This callback is called in the user interface thread. 

When calling ColculateMogicNumberAsync (which, as you’ll recall, is inside a try block), you 
create an object of type Progress with the callback method you’ve defined and pass that as the last 
argument: 

magicNum = await CalculateMagicNumberAsync("xyz", 333, cts.Token, 

new Progress<doubl e> (ProgressCal1 back)); 

The progress callback doesn’t need to be a separate function. It can be a simple lambda 
expression: 

magicNum = await CalculateMagicNumberAsync("xyz", 333 ， cts.Token, 

new Progress<double>( (percent) => progressBar.Value = percent)); 

Let’s look at a real example. 

For the author of a programming tutorial, one of the hard parts of demonstrating asynchronous 
operations is coming up with a reasonably simple example that requires an appreciable amount of 
time to execute. One finds oneself deliberately writing inefficient code just so that there’s time to see 
the ProgressBar move and to hit the Cancel button before the job is done! 

The WordFreq project reads a text file — such as a plain-text e-book from the famous Project 
Gutenberg website — and calculates word frequencies, letting you determine, for example, how many 
times the word "whale” appears in Herman Melville’s Moby-Dick. In fact, WordFreq is hard-coded 
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for Moby-Dick, but of course the word-counting code in the Get Wo rdFreq uen ciesA syn c method is 
generalized. 

GetWordFrequenciesAsync has a .NET Stream argument because I wanted to use the .NET 
StreamReader within the method to read the file line by line. It also includes CancellationToken and 
I Progress arguments. 

But the return value is a bit hairy. The method uses a .NET Dictionary object to accumulate the 
counts of each unique word in the file. Hence, the Dictionary key is of type string and the value is 
of type int. At the end of the method, the LINQ OrderByDescending function sorts the dictionary by 
value — that is, the highest frequency words at the beginning. The result is a collection of objects of 
type: 

KeyValuePai r<stri ng , i nt> 

The actual collection returned by OrderByDescending is an object of the generic type 
/Ordered Enumerable: 

IOrderedEnumerabl e<KeyVal uePai r<stri ng , i nt» 

This means that the return value of the GetWordFrequenciesAsync method is: 

Task<IOrderedEnumerabl e<KeyVal uePai r<stri ng , i nt»> 

And here it is: 

Project: WordFreq I File: MainPage.xaml.es (excerpt) 

Tasl«IOrderedEnumerable<KeyValuePai r<string , i nt»> GetWordFrequenciesAsync(Stream stream, 

Cancel 1ationToken cancel 1ationToken, 
IProgress<doubl e> progress) 

{ 

return Task. Run(async ()=> 

{ 

Dicti onary<stri ng , int> dictionary = new Dicti onary<stri ng , i nt>() ; 

using (StreamReader StreamReader = new StreamReader (stream)) 

{ 

// Read the first line 

string line = await StreamReader.ReadLineAsync(); 


while (line != null) 

{ 

cancel 1ationToken.ThrowlfCancel1ationRequested(); 
progress.Report(100.0 * stream.Position / stream.Length); 

string：] words = line.SplitC* *, ‘，， ， ‘_，， ‘； ’， ‘： ，）； 

foreach (string word in words) 

{ 

string charWord = word.ToLowerO ; 


while (charWord.Length > 0 && ! Char. IsLetter(charWord[0])) 
charWord = charWord.Substring(l); 
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while (charWord.Length > 0 && 

!Char. IsLetter(charWord[charWord.Length - 1])) 
charWord = charWord.Substring(0, charWord.Length - 1); 

if (charWord.Length == 0) 
conti nue; 

if (dictionary.ContainsKey(charWord)) 
dictionary[charWord] += 1; 

else 

dicti onary.Add(charWord, 1); 

} 

line = await streamReader.ReadLineAsync(); 


// Return the dictionary sorted by Value (the word count) 
return dictionary.OrderByDescending(i => i.Value); 

}, cancel 1ationToken); 

} 


Notice that the body of the method passed to Task.Run has occurrences of the await operator with 
calls to the ReadLineAsync method of StreamReader. Consequently, the lambda function passed to 
Task.Run is flagged with async. For every line in the file, the ConcellationToken is checked and prog¬ 
ress is reported as a percentage based on the amount of the Stream object that’s been read. The 
Project Gutenberg e-book of Moby-Dick contains over 22,000 lines, so these two calls are rather too 
frequent, but reducing their number probably involves keeping track of line counts. 

This method has no exception handling. If the StreamReader constructor or ReadLineAsync call 
raises an exception, that must be handled by the code calling this method. 

The XAML file for the program has two buttons for Start and Cancel (the latter initially disabled), a 
ProgressBar for reporting progress, a TextBlock for reporting errors, and a StockPanel in a ScrollViewer 
for the list of words and word counts: 

Project: WordFreq | File: MainPage.xaml (excerpt) 

<Grid Background=" {StaticResource ApplicationPageBackgroundThemeBrush}"> 

<Grid HorizontalAli gnment="Center"> 

<Grid.RowDefinitions> 

〈RowDefinition Height="Auto" /> 

〈RowDefinition Height="Auto" /> 

< RowDefinition Hei ght="Auto" /> 

< RowDefinition Height="*" /> 

</Grid.RowDefinitions> 

<Grid.ColumnDefinitions> 

<ColumnDefinition Width="*" /> 

<Co1umnDefinition Width="*" /> 

</Grid.ColumnDefinitions> 
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〈Button Name=" startButton" 

Content="Start" 

Grid. Row="0" Grid.Col umn="0" 

HorizontalAli gnment="Center" 

Margin="24 12" 

Cli ck="OnStartButtonClick" /> 

<Button Name="cancel Button" 

Content="Cancel " 

Grid. Row="0" Grid.Column="l" 

IsEnabled="fal se" 

HorizontalAli gnment="Center" 

Margin="24 12" 

Cli ck="OnCancel ButtonClick" /> 

<ProgressBar Name=" progressBar" 

Grid.Row="l" Grid.Col umn="0" Grid.ColumnSpan="2" 
Margin="24" /> 

<TextBlock Name="errorText" 

Grid. Row="2" Grid.Col umn="0" Grid.ColumnSpan="2" 
FontSize="24" 

TextWrappi ng="Wrap" /> 

〈ScrollVi ewer Grid. Row="3" Grid.Col umn="0" Grid.Col umnSpan="2"> 
〈StackPanel Name="stackPanel " /> 

</ScrollViewer> 

</Grid> 

</Grid> 


The code-behind file contains the GetWordFrequenciesAsync method as well as a couple of short 
methods for cancellation and progress: 

Project: WordFreq I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

// Project Gutenberg ebook of Herman Melville’s "Moby-Dick" 

Uri uri = new Uri ("http://www.gutenberg.org/ebooks/2701.txt.utf-8 n ) ; 

CancellationTokenSource cts; 


public MainPageO 

{ 

this .Ini tializeComponent(); 

} 

async void OnStartButtonCli ck(object sender, RoutedEventArgs args) 


} 

void OnCancelButtonCli ck(object sender, RoutedEventArgs args) 

{ 

cts.Cancel(); 

} 
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void ProgressCal1 back(doubl e progress) 

{ 

progressBar.Value = progress; 

} 

Task<IOrderedEnumerable<KeyValuePai r<string , int»> GetWordFrequenciesAsync(Stream stream, 

Cancel 1ationToken cancel 1ationToken, 
IProgress<double> progress) 



The only code you haven’t seen yet is the Click handler for the Start button. The handler is 
designed to be called multiple times while the program is running, but it’s not re-entrant — that is, 
it's not designed to be started a second time until it's exited the first time. Much of the logic in the 
method involves initializing the StockPonel, initializing the ProgressBar, and enabling and disabling the 
buttons. Notice all the file accesses as well as the call to GetWordFrequenciesAsync are in a try block: 

Project: WordFreq | File: MainPage.xaml.es (excerpt) 

async void OnStartButtonCli ck(object sender, RoutedEventArgs args) 

{ 

stackPanel.Children.Clear(); 
progressBar.Value = 0; 
errorText.Text = "" ; 
startButton.IsEnabled = false; 

IOrderedEnumerabl e<KeyVal uePai r<stri ng , i nt» wordLi st = null; 
try 

RandomAccessStreamReference streamRef = RandomAccessStreamReference.CreateFromUri(uri); 

using (IRandomAccessStream raStream = await streamRef.OpenReadAsyncO) 

{ 

using (Stream stream = raStream.AsStream()) 

{ 

cancel Button.IsEnabled = true ; 

cts = new Cancel 1ationTokenSource() ; 

wordList = await GetWordFrequenciesAsync(stream, cts.Token, 

new Progress<doubl e>( ProgressCal1 back)); 

cancel Button.IsEnabled = false; 

} 

} 

} 

catch (OperationCanceledException) 

{ 

progressBar.Value = 0; 
cancel Button.IsEnabled = false; 
startButton.IsEnabled = true ; 
return ; 

} 
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catch (Exception exc) 


progressBar.Value =0; 
cancel Button.IsEnabled = false; 
startButton.IsEnabled = true ; 
errorText.Text = "Error : " + exc.Message; 
return ; 

} 

// Transfer the list of words and counts to the StackPanel 
foreach (KeyVal uePai r<string , int> word in wordList) 

{ 

if (word.Value > 1) 

{ 

TextBlock txtblk = new TextBlock 
{ 

FontSize = 24 ， 

Text = word.Key + " \x2014 " + word.Value.ToString() 

}； 

StackPanel.Children.Add(txtblk); 

} 

await Task.Yi eld(); 


startButton■IsEnabled = true; 

} 


But another issue has arisen: After the asynchronous method has returned, the program must 
transfer the items into the StackPanel. This job is handled by the foreach block at the end of the 
method. This loop involves extreme interaction with user interface objects — creating a TextBlock and 
adding it to the StackPanel — and it simply can’t be handled in another thread. Even limiting the list 
to those words that show up at least twice in Moby-Dick (as I've done) involves almost 10,000 items. 
Such a loop has the potential of freezing the user interface, preventing it from responding to user 
input, and even preventing the prompt appearance of the items on the screen. 

The solution — not entirely successful — involves this statement: 

await Task.Yi eld(); 

This call with await effectively allows other code on the user interface thread to run and then returns 
when that code has completed. The other code that executes includes code implemented in the 
StackPanel class that lays out the TextBlock children and user input that might want to scroll the 
StackPanel within the ScrollViewer. 

Without that call to Task-Yield, the list of words doesn’t appear on the screen for about five seconds 
after the ProgressBar has signaled maximum progress. To be sure, the repeated calls to Task-Yield 
slow down the loop considerably. It will take longer to complete (as you can see for yourself when 
running the program by the delay before the Start button is enabled), but you'll see results almost 
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immediately. You should also be able to scroll the list before it has completed, and you’ll discover that 
the Moby-Dick file contains 963 occurrences of the word "whale": 



him — 1046 
so—1046 
whale — 963 
you — 930 
one _ 892 
or —795 
had — 111 
have — 771 
there — 771 
now — 768 
were — 681 
they _ 661 
which — 648 
their 一 619 
then _ 619 
are — 616 
some — 615 
me — 612 
when — 599 
an — 594 
my — 587 


A better solution for this program is not to use a StockPanel at all. As you’ll discover in Chapter 11, 
"The Three Templates,” there are controls specifically for displaying lists of items. These controls can 
use a VirtuolizingStockPonel, which doesn’t create actual elements until they are scrolled into view. 

Although Windows 8, .NET, and C# have made working with asynchronous methods easier than 
ever, attention to detail and testing are still required. For example, on the machine I’m using for this 
book, the G etWordFrequenciesAsync method requires three to four seconds to finish. However, if I 
remove the check for cancellation and progress reporting, the method requires less than one second. 

I don’t know about you, but I find it questionable whether cancellation and progress are suitable for a 
one-second asynchronous method. 


These things are not easy, and they’re not easy because in one sense weYe trying to do the 
impossible: We’re trying to give our computers lots of work to do but make it seem as if they’re doing 
nothing at all. Windows 8 applications should appear as if they can engage in heavy lifting without 
breaking a sweat, and that’s still a challenge for programmers. 


260 PART : Elementals 



CHAPTER 8 


App Bars and Popups 


y assembling the elements, controls, and panels discussed in Chapter 4, "Presentation with Panels," 

and Chapter 5, "Control Interaction," it is possible to construct an entire user interface on the 
surface of a page. But for many programs, it’s preferable that most commands and program options 
remain hidden until the user specifically needs to use them. 

Windows applications of the past generally used menus and dialog boxes to consolidate 
commands and options. While the top level of a menu always remains visible, the actual commands 
are usually on drop-down submenus. Some menu commands have the effect of invoking a dialog box 
for presenting a group of related program options. 

Windows 8 instead places emphasis on application content rather than chrome. In many cases, 
program options formerly on an application menu will be moved to an application bar, which is 
normally hidden from view but invoked when the user sweeps a finger on the top or bottom edge 
of the screen, or moves the mouse pointer to that location. The application bar is a ContentControl 
derivative named AppBor, and I’ll show you how to use it in this chapter. 

In addition, a Windows 8 program can display a list of commands in a simple object of type 
PopupMenu (often used as a context menu) or a more extensive collection of controls that you 
present to the user through an element named Popup. Ill show you how to use both types of popups 
in this chapter. 

This chapter concludes with the most extensive application so far in this book — a program called 
XamICruncher that lets you interactively experiment with XAML. 


Implementing Context Menus 

A context menu is a menu that is invoked with a right click of a mouse or a press-hold-and-release 
finger gesture. The menu pops up at the point where the screen was touched and generally disap¬ 
pears when one of the commands is selected. Very often, the context menu is associated with a 
particular control or a particular area of a single control; this is what justifies the "context” part of 
the name. 
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The TextBox control includes a context menu. To see it, run any program in this book that uses a 
TextBox. Type some text into it, select some, and then right-click the control or perform the press- 
hold-and-release gesture. A menu appears that potentially contains up to five commands, depending 
on the selection and the state of the clipboard: 


Let's 


Cut 
Copy 
Paste 
Undo 
Select All 


ontext menu! 


To make your own custom context menu you create an object of type PopupMenu. This class is 
defined in the Windows. Ul. Pop ups namespace along with MessageDialog (which you encountered in 
Chapter 7, "Asynchronicity") and UlCommond, which is what you use to specify commands in both 
MessageDialog and PopupMenu. 


PopupMenu derives from Object, so it’s very unlikely that you’ll instantiate it in a visual tree in a 
XAML file. Instead, you’ll probably want to construct a PopupMenu object entirely in code at the time 
it’s invoked, most likely in response to a RightTapped event. 

Here’s a XAML file containing a TextBlock centered on the page with a handler assigned for the 
RightTapped event: 


Project: SimpleContextMenu | File: MainPage.xaml (excerpt) 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
〈TextBlock Name="textBl ock" 

FontSize="24" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Center" 

TextAli gnment="Center" 

Ri ghtTapped="OnTextBl ockRightTapped"> 

Simple Context Menu 
<LineBreak /> 

<LineBreak /> 

(right-click or press-and-hold-and-release to invoke) 
</TextBlock> 

</Grid> 
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Just as with MessageDialog, you indicate the commands you want to appear on the menu with 
instances of UlCommond. Call ShowAsync to display it: 

Project: SimpleContextMenu | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 
{ 

public MainPageO 
{ 

this .Ini ti alizeComponent(); 

} 


async void OnTextBlockRightTapped (object sender, RightTappedRoutedEventArgs args) 

{ 

PopupMenu popupMenu = new PopupMenuO ; 

popupMenu.Commands .Add(new UlCommandC" Larger Font" , OnFontSizeChanged, 1.2)); 
popupMenu.Commands .Add(new UlCommand ("Smaller Font" , OnFontSizeChanged, 1 / 1.2)); 
popupMenu.Commands .Add(new UlCommandSeparatorO) ; 

popupMenu.Commands.Add (new UICommandC'Red", OnColorChanged, Colors .Red)); 
popupMenu.Commands.Add (new UICommandC'Green", OnColorChanged, Colors .Green)); 
popupMenu.Commands.Add (new UICommand("Bl ue" , OnColorChanged, Colors. Blue)); 

await popupMenu.ShowAsync(args.GetPosition (thi s) ); 


void OnFontSizeChanged(IUICommand command) 

{ 

textBlock.FontSize *= (doubl e) command■Id; 

} 


void OnColorChanged (IUICommand command) 

{ 

textBlock.Foreground = new Soli dColorBrush((Color)command.Id); 

} 

} 

Notice the UlCommondSeparotor object to create a horizontal line in the menu. 

Just as with MessageDialog, the ShowAsync call returns an object of type 
IAsyncOperation<IUICommond> l from which you can obtain the command selected by the user. I 
have chosen instead to specify two custom handlers for the commands in the UlCommand construc¬ 
tors, and I've used the third argument of that constructor to specify a value that helps the handler 
process the command with as little fuss as possible. 

The ShowAsync method requires a Point value to indicate where the menu is to be displayed. This 
point should be relative to the application’s window, which usually means that it can be relative to the 
page. The menu is generally horizontally centered at this point and positioned vertically above the 
point. This makes sense for a touch interface: You don’t want the menu obscured by the user’s hand! 
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Here’s how it appears when I right-click at the top of the 'S' in "Simple”: 



Of course, if you click outside the TextBlock, nothing will happen. 

If the point you specify is too close to the left, top, or right edge of the window, the location will 
be automatically shifted so that the menu is not cropped. The menu is always displayed with black 
text on a white background regardless of the RequestedTheme value. 

The menu has a keyboard interface, but not much of one: You can use the arrow keys to move 
a selection among the items, and then press Enter to choose one. The menu disappears when you 
select a command, if you tap or click anywhere outside the menu, or if you press any other key on the 
keyboard. If you choose to process the lUICommond object returned from Show A sync, that object will 
be null if the menu was dismissed without a command being selected. 

You have now seen virtually everything you can do with PopupMenu. The only other option is an 
alternative method to invoke the menu called ShowForSelectionAsync. This method requires a Red 
value and an optional member of the Placement enumeration, which has members Default, Above, 
Below, Left, and Right. This is only a preferred location: The actual location will be chosen so that the 
entire menu appears within the program’s window. 

You can’t display any commands in a PopupMenu in a shaded disabled state. If a particular com¬ 
mand isn’t currently applicable, don’t include it! 

Nor can you display any commands with check marks to indicate a selected item. If you want to 
display anything beyond simple commands, you need to graduate from PopupMenu to Popup. 
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The Popup Dialog 


The Popup class (which derives from FromeworkElement) is the closest thing the Windows Runtime has 
to the traditional dialog box. Popup has a Child property of type ill Element that you’ll likely set to a 
Panel containing a bunch of controls or to a Border with a Panel child. 

The SimpleContextDialog project is functionally equivalent to the previous project, and the XAML 
file is very similar: 


Project: SimpleContextDialog | File: MainPage.xaml (excerpt) 

<Grid Background=" {StaticResource ApplicationPageBackgroundThemeBrush}"> 
〈TextBlock Name="textBl ock" 

FontSize="24" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Center" 

TextAli gnment="Center" 

Ri ghtTapped="OnTextBl ockRightTapped"> 

Simple Context Dialog 
<LineBreak /> 

<LineBreak /> 

(right-click or press-hold-and-release to invoke) 

</TextBlock> 

</Grid> 


The handler for the RightTapped event on the TextBlock assembles two Button controls and three 
RadioButton controls in a Stack Pan el that is made a child of a Border that is then set to the Child prop¬ 
erty of a Popup. That’s the long part. Much shorter are the Click handler for the Button controls and 
the Checked handler for the RadioButton controls: 

Project: SimpleContextDialog | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

public MainPageO 

{ 

this. Ini ti alizeComponent(); 

} 

void OnTextBlockRightTapped (object sender, RightTappedRoutedEventArgs args) 

{ 

StackPanel stackPanel = new StackPane" (); 

// Create two Button controls and add to StackPanel 
Button btnl = new Button 
{ 

Content = "Larger font" , 

Tag = 1.2, 

HorizontalAlignment = HorizontalAlignment .Center, 

Margin = new Thi ckness(12) 

}； 
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btnl.Click += OnButtonClick; 
stackPanel.Chi Idren.Add(btnl); 


Button btn2 = new Button 

{ 

Content = "Smaller font" , 

Tag = 1 / 1.2, 

Horizontal Alignment = Horizontal A1 ignment .Center, 

Margin = new Thi ckness(12) 

}； 

btn2.Click += OnButtonClick; 
stackPanel.Children.Add(btn2); 

// Create three RadioButton controls and add to StackPanel 
string[] names = { "Red" , "Green" , "Blue" }; 

Color[] colors = { Colors. Red, Colors .Green, Colors .B1ue }; 

for (int i =0; i < names.Length; i++) 

{ 

RadioButton radioButton = new RadioButton 

{ 

Content = names[i], 

Foreground = new SolidColorBrush (colors[i]), 

IsChecked = (textBlock.Foreground as SolidColorBrush) .Color == colors[i], 

Margin = new Thi ckness(12) 

}； 

radioButton.Checked += OnRadioButtonChecked; 
stackPanel.Children.Add(radioButton); 

} 

// Create a Border for the StackPanel 
Border border = new Border 
{ 

Child = stackPanel, 

Background = 

this. Resources ["ApplicationPageBackgroundThemeBrush"] as SolidColorBrush, 
BorderBrush = this .Resources ["ApplicationForegroundThemeBrush"] as SolidColorBrush, 
BorderThickness = new Thi ckness(l) , 

Padding = new Thickness (24), 

}； 

// Create the Popup object 
Popup popup = new Popup 
{ 

Child = border, 

IsLightDismissEnabled = true 

}； 

// Adjust location based on content size 
border.Loaded += (loadedSender, loadedArgs)=> 

{ 

Point point = args.GetPosition (thi s); 
point.X -= border.ActualWidth / 2; 
point.Y -= border.Actual Height; 
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// Leave at least a quarter inch margin 
popup.HorizontalOffset = 

Math .Mi n(thi s .ActualWidth - border.ActualWidth - 24 ， 

Math.Max(24, point.X)); 

popup.VerticalOffset = 

Math .Mi n(thi s .ActualHeight - border.ActualHeight - 24, 

Math .Max(24 ， point.Y)); 

// Set keyboard focus to first element 
btnl.Focus (FocusState .Programmatic); 

}； 

// Open the popup 

popup.IsOpen = true; 

} 

void OnButtonCli ck(object sender, RoutedEventArgs args) 

{ 

textBlock.FontSize *= (doubl e) (sender as Button) .Tag; 

} 

void OnRadioButtonChecked(object sender, RoutedEventArgs args) 

{ 

textBlock.Foreground = (sender as RadioButton) .Foreground; 

} 

} 

To position the Popup, it is necessary to set the HorizontalOffset and VerticolOffset properties 
to values relative to the program’s window. However, these properties cannot be set intelligently 
without knowing the size of the content that the Popup is hosting, and that’s generally not available 
until the Popup is displayed. For that reason, this code sets a Loaded handler on the Border, which is 
the content element of the Popup. The Popup is then positioned centered above the right-tap point 
(much like PopupMenu), but I've also allowed at least a 24-pixel margin between the Popup and the 
program’s window. 

The RightTopped handler concludes by setting the IsOpen property of the Popup to true. This 
causes the Popup to be displayed on the screen. Normally the user can still interact with the rest of 
the program’s page. But notice that the IsLightDismissEnabled property of the Popup is set to true. 
This allows the Popup to be dismissed with a click or a tap outside the Popup or with a press of the 
Esc key. Without this property set, multiple copies of this dialog can be displayed and the program 
would need to remove the Popup from the screen by setting the IsOpen property of false, probably in 
response to an event of one of the child controls. Popup also defines Opened and Closed properties if 
you need that information for initialization or cleanup. 
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Here’s a click on the upper end of the right parenthesis with the font already having been 
increased in size: 


Simple Context Dialog 


Larger font 


Smaller font 


Green 

QBIue 


(right-click or press-hold-and-release to invoke) 


You can use the Tab key to navigate among the items. By default these dialogs have the same color 
theme as the application, so using a So/x/e 厂 as I’ve done helps to set off the dialog visually on the 
page. 


This dialog box has no OK or Cancel button. Instead, I’ve implemented this dialog so that clicking 
the buttons changes the underlying display immediately and the Popup is dismissed by clicking or 
pressing anywhere outside it. In more complex dialogs, you might want a button to restore defaults. 


Of course, defining the entire content of the Popup in code is a nuisance. It’s more common to 
define a UserControl specifically for the dialog and then make an instance of that the child of the 
Popup. However, you then need to provide some way for this UserControl to convey the user selec¬ 
tions back to the program, and the best way to do that is with bindings between the dialog and the 
application, either directly or through a view model. You’ll see examples of both approaches later in 
this chapter. 


Application Bars 

The Windows 8 application bar is intended to implement program commands and options in a 
manner similar to a traditional menu or toolbar. The application bar is a class named AppBor, and it 
is invoked when the user sweeps a finger on the top or bottom of the screen. Application bars can 
appear at the top of the page, the bottom, or both. The application bar often disappears when a 
command has been selected, but that’s not required. 

The Page class defines two properties named TopAppBor and BottomAppBor that you generally 
set to AppBar tags in XAML. AppBar derives from ContentControl, and you’ll usually set the Content 
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property to a panel that contains the controls that appear on the application bar. AppBar does not 
have a fixed height: The height is based on the controls it hosts. 

Certainly the best way to become familiar with the use of application bars in real programs is to 
explore some of the standard applications that are part of Windows 8. Mostly you’ll see applica¬ 
tion bars that consist of a row of circular Button controls, but the application bars in the Windows 8 
version of Internet Explorer demonstrate that an application bar can contain a variety of controls. In 
Internet Explorer, the bottom application bar contains a TextBox into which you can type a URL; the 
top application bar displays a collection of visited web pages. 

Here’s a program with a rather unconventional pair of application bars: 


Project: UnconventionalAppBar I File: MainPage.xaml (excerpt) 

<Page … > 

<Grid Background="Li ghtGray"> 

<TextBlock Name="textBlock" 

Text="Unconventi onal App Bar" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Center" 

FontSi ze="{Binding ElementName=sl ider, Path=Val ue}" /> 

</Grid> 


<Page.TopAppBar> 

<AppBar Name="topAppBar"> 
<S1ider Name="sl ider" 
Minimum="8" 
Maximum="196" 
Value="24" /> 

</AppBar> 

</Page.TopAppBar> 


<Page.BottomAppBar> 

<AppBar Name="bottomAppBar"> 

<StackPanel Orientati on="Hori zontal" 

HorizontalAlignment="Ri ght"> 

〈Button Content="Red" 

Foreground="Red" 

Margin="24 12" 

Cli ck="OnAppBarButtonClick" /> 


<Button Content="Green" 

Foreground="Green" 

Margin="24 12" 

Cli ck="OnAppBarButtonClick" /> 

〈Button Content="Bl ue" 

Foreground="Bl ue" 

Margin="24 12" 

Cli ck="OnAppBarButtonClick" /> 
</StackPanel> 

</AppBar> 

</Page.BottomAppBar> 

</Page> 
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Again, a TextBlock sits in the center of the screen, but this one has its Font Size bound to a Slider 
that is the only content of an AppBor that appears at the top. The second AppBor is set to the 
Bottom AppBar property and contains a horizontal Stock Pan el with three Button controls. The Button 
controls share a Click handler in the code-behind file: 

Project: UnconventionalAppBar I File: MainPage.xaml.es (excerpt) 

void OnAppBarButtonCli ck(object sender, RoutedEventArgs args) 

{ 

textBlock.Foreground = (sender as Button) .Foreground; 

} 

It is generally much easier working with an application bar than a Popup or PopupMenu because 
the AppBar is part of the visual tree of the page, which eases the setting of bindings and event 
handlers. The only difference between controls on an AppBar and controls on the page is that the 
application bars are usually not visible until the user sweeps a finger on the top or bottom of the 
screen. At that point, the user can interact with the controls: 


Unconventional App Bar 


An application bar and controls are colored according to the RequestedTheme of the application, 
which is set to Light in this program. I gave the main Grid a LightGroy background to contrast with 
those colors. Most programs that use application bars seem to have Dork themes. 

An application bar is automatically dismissed and goes back into hiding when you click or press 
anywhere outside the application bar, or if you press Esc. If you prefer that the application bar is not 
dismissed in this way, set the IsSticky property oi AppBor to true. In that case, to get rid of the applica¬ 
tion bar, the user needs to perform another finger sweep or you’ll need to set the IsOpen property of 
one or both AppBor objects to false in the code-behind file. 

There are some cases where a program might want to dismiss the application bar from code. For 
example, in this particular program, to change the text color, a user needs to bring up the applica¬ 
tion bar with a finger sweep, press a button, and then dismiss the application bar with another finger 
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sweep or by pressing outside the bar. You might choose to dismiss the application bars from code 
when a button is pressed: 


void OnAppBarButtonCli ck(object sender, RoutedEventArgs args) 

{ 

textBlock.Foreground = (sender as Button). Foreground; 
topAppBar.IsOpen = false; 
bottomAppBar.IsOpen = false; 

} 

This is very common, and you know you’ll need to do it when you get tired of dismissing an 
application bar after you’ve clicked a button on it. However, sometimes the user might find it conve¬ 
nient to set several options in a row without re-invoking the application bar. This is a judgment call. 

Some applications might want to require the user to interact with an application bar the first time 
the program is run. In that case, initializing the IsOpen property to true is fine. Like Popup, AppBar has 
Opened and Closed events for initialization and cleanup. 

The Application Bar Button Style 

Many Windows 8 applications have only a bottom application bar containing a row of circular Button 
controls. The buttons are usually identified both with a symbol in a circle and a short text command. 

The basis of this circular button is a Style defined in StandardStyles.xaml with the key name 
AppBarButtonStyle. StandardStyles.xaml is the file located in the Common folder of every C#, Visual 
Basic, or C++ Windows 8 project created by Visual Studio. The file is included in the Resources section 
of the App.xaml file and hence is available to any Windows 8 application. 

The AppBarButtonStyle Style definition contains a long ControlTemplate that defines the visuals 
of this circular button. You might want to take a closer look at this ControlTemplate after assimilating 
Chapter 11, "The Three Templates.” Meanwhile, you can just use this Style without knowing exactly 
how the template works. 

The AppBarButtonStyle contains a Setter object that sets the Font Family to Segoe Ul Symbol, and 
the symbol that appears in the button is a character from this font. 


As the name indicates, Segoe Ul Symbol is a symbol font. However, it is not like an old-fashioned 
symbol font where a bunch of symbols replace the common letters and numbers. The normal char¬ 
acters still exist in this font, and you can use this font for normal purposes. But the Unicode standard 
allows fonts such as this to include custom characters by defining the range of codes from OxEOOO 
through 0xF8FF as a "private use area,” which means that these character codes are font-specific. 

The Segoe Ul Symbol doesn’t fill up this whole area with custom symbols, but the range of OxElOO 
through 0xElF4 is a collection of glyphs that symbolize a bunch of common computer chores and 
hence are suitable for application bar buttons. 
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For example, if you want to display a button with a little house and the word "Home," you can put 
such a button on an application bar like so: 


<Page.BottomAppBar> 

<AppBar> 

<StackPanel Orientati on="Hori zontal "> 

<Button Style="{StaticResource AppBarButtonStyl e} 
Content="&#xE10F ;" 

AutomationProperties. Name="Home" 

Cli ck="OnButtonCl ick" /> 


</StackPanel> 

</AppBar> 

</Page.BottomAppBar> 


You’ve seen the Content and Click attributes before. The Automation Properties class is a collection 
of attached properties, of which Nome is one. These properties normally allow user interface 
elements to be identified for purposes of testing, and for accessibility by assistive technologies 
such as screen readers. The ControlTemplate defined within AppBarButtonStyle references the 
Automation Properties. Nome property to display a text string under the button. Here’s how this 
particular button appears with a dark theme: 



The StandardStyles.xaml file also defines individual styles based on AppBarButtonStyle for many 
(but not all) of the Segoe Ul Symbol character codes from OxElOO through 0xElE9. For example, 
here’s a Style definition for HomeAppBarButtonStyle: 

<Style x : Key="HomeAppBarButtonStyl e" TargetType=" ButtonBase" 

BasedOn="{Stati cResource AppBarButtonStyl e}"> 

〈Setter Property="Automati onProperties.Automationld" Val ue="HomeAppBarButton"/> 

<Setter Property="Automati onProperties.Name" Val ue="Home"/> 

〈Setter Prope rty="Con tent" Val ue="&#xE10F ;"/> 

</Style> 


Obviously these styles can be very handy because someone has already matched up the symbols, 
names, and suggested functionality. However, in the standard StandardStyles.xaml files, these styles 
are all commented out and you need to remove the comments in order to use them. Here’s how you 
would reference this Style in a XAML file: 

〈Button Styl e="{StaticResource HomeAppBarButtonStyle}" 

Cl ick="OnButtonCl ick" /> 

But feel free to specify your own text if you want: 

〈Button Styl e="{StaticResource HomeAppBarButtonStyle}" 

AutomationProperties. Name="Head on Home" 

Click="OnButtonClick" /> 
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Wouldn’t it be nice to get a complete list of the application bar button styles 
defined in StandardStyles.xaml with the symbols and text labels? That’s provided by the 
LookAtAppBarButtonStyles program. The XAML file contains a ScrollViewer and StockPonel ready 
for filling, and an application bar with a couple standard RadioButton controls: 

Project: LookAtAppBarButtonStyles | File: MainPage.xaml (excerpt) 

<Page … > 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

〈ScrollViewer FontSi ze="20"> 

〈StackPanel Name="stackPanel " /> 

</Scro"ll Vi ewer> 

</Gri d> 


<Page.BottomAppBar> 

<AppBar> 

<StackPanel Orientation="Horizontal "> 

<RadioButton Name=" symbolSortRadio" 

Content="Sort by symbol" 
Checked="OnRadi oButtonChecked" /> 


<RadioButton Name="textSortRadi o" 


</StackPanel> 

</AppBar> 

</Page.BottomAppBar> 
</Page> 


Content="Sort by text" 
Checked="OnRadi oButtonChecked" /> 


In the handler for the Loaded event, the code-behind file gets access to the ResourceDictionory 
provided by StandardStyles.xaml by referencing the MergedDictionaries property of the Resources 
collection associated with the current Application instance. The code locates the Style with the key 
name "AppBarButtonStyle” and then saves all Style instances with a Based On property equal to that 
Style in a collection of type Item, an internal class: 


Project: LookAtAppBarButtonStyles | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

class Item 

{ 

public string Key; 
public char Symbol; 
public string Text; 

} 


List<Item> appbarStyles = new List<Item>() ; 

FontFamily segoeSymbolFont = new FontFami lyC'Segoe UI Symbol ”）； 


public MainPageO 

{ 

this .Ini tializeComponent(); 
Loaded += OnLoaded; 

} 
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void OnLoaded(object sender, RoutedEventArgs args) 

{ 

// Basically gets StandardStyles.xaml 

ResourceDictionary dictionary = Application. Current.Resources.MergedDictionaries[0]; 
Style baseStyle = dictionary ["AppBarButtonStyle"] as Style; 

// Find all styles based on AppBarButtonStyle 
foreach (object key in dictionary.Keys) 

{ 

Style style = dictionary[key] as Style; 

if (style != null && style.BasedOn == baseStyle) 

{ 

Item item = new Item 

{ 

Key = key as string 

}； 

foreach (Setter setter in style.Setters) 

{ 

if (setter.Property.Equal s(AutomationProperties .NameProperty)) 
item.Text = setter.Value as string; 

if (setter.Property.Equals (ButtonBase .ContentProperty)) 
item.Symbol = (setter.Value as string) [0]; 

} 

appbarStyles.Add(item); 

} 

} 

// Display items by checking RadioButton 
symbolSortRadio.IsChecked = true ; 

} 

} 

The Loaded event concludes by checking one of the two RadioButton controls in the application 
bar. This causes a call to the Checked handler for the RadioButton, which sorts the collection of styles 
in one of two different ways: 

Project: LookAtAppBarButtonStyles | File: MainPage.xaml.es (excerpt) 

void OnRadioButtonChecked (object sender, RoutedEventArgs args) 

{ 

if (sender == symbolSortRadio) 

{ 

// Sort by symbol 

appbarStyles.Sort((iteml, item2)=> 

{ 

return iteml.Symbol.CompareTo(item2.Symbol); 

})； 

} 

else 
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// Sort by text 

appbarStyles.Sort((iteml, item2)=> 

{ 

return iteml.Text.CompareTo(item2.Text); 

}); 

} 

// Close app bar and display the items 
this. BottomAppBar.IsOpen = false; 

DisplayListO ; 

} 

Processing of the Checked handler concludes with a call to DisployList that creates lines of text for 
each item. (Notice that the FontFomily for the first Text Block in each line uses the Segoe U1 Symbol 
font.) Each of these items is added to the StockPanel in the ScrollViewer. 

Project: LookAtAppBarButtonStyles I File: MainPage.xaml.es (excerpt) 

void DisplayListO 

{ 

// Cl ear the StackPanel 
stackPanel.Children.Clear(); 

// Loop through the styles 
foreach (Item item in appbarStyles) 

{ 

//A StackPanel for each item 

StackPanel itemPanel = new StackPanel 

{ 

Orientation = 0 门 _entation ■Horizontal ， 

Margin = new Thickness(0, 6, 0, 6) 

}； 


// The symbol itself 
TextBlock textBlock = new TextBlock 
{ 

Text = item.Symbol .ToStringO , 
FontFamily = segoeSymbolFont, 

Margin = new Thickness (24, 0, 24 ， 0) 

}； 

itemPanel.Children.Add(textBlock); 


// The Uni code 'identifier 
textBlock = new TextBlock 
{ 

Text = "Ox" + C(int) item.Symbol).ToString("X4"), 
Width = 96 

}； 

itemPanel.Children.Add(textBlock); 


// The text for the button 
textBlock = new TextBlock 


Text = + item.Text + 

Width = 240, 



}； 
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itemPanel.Children.Add(textBlock); 


// The key name 
textBlock = new TextBlock 
{ 

Text = item.Key 

}； 

itemPanel.Children.Add(textBlock); 
stackPanel.Chi Idren.Add(itemPanel); 

} 

} 

Here’s an excerpt of part of the list: 


回 

0xE144 

"Keyboard" 

KeyboardAppBarButtonStyle 

E 

0xE145 

"Dock Left" 

DockLeftAppBarButtonStyle 

□ 

0xE146 

"Dock Right" 

DockRightAppBarButtonStyle 

B 

0xE147 

"Dock Bottom" 

DockBottomAppBarButtonStyle 

>< 

0xE148 

■•Remote" 

RemoteAppBarButtonStyle 

c 

0xE149 

"Sync" 

SyncAppBarButtonStyle 

o 

0xE14A 

■•Rotate" 

RotateAppBarButtonStyle 

u 

0xE14B 

"Shuffle" 

ShuffleAppBarButtonStyle 

!= 

0xE14C 

"List" 

ListAppBarButtonStyle 

i 

0xE14D 

..Shop" 

ShopAppBarButtonStyle 

[ss| 

0xE14E 

"Select AII M 

SelectAIIAppBarButtonStyle 


0xE14F 

"Orientation" 

OrientationAppBarButtonStyle 

<-l 

0xE150 

"Import" 

ImportAppBarButtonStyle 

<-ss 

0xE151 

"Import All" 

ImportAIIAppBarButtonStyle 

□ 

0xE155 

"Browse Photos" 

BrowsePhotosAppBarButtonStyle 

A 

0xE156 

"Webcam" 

WebcamAppBarButtonStyle 

「口 

0xE158 

"Pictures" 

PicturesAppBarButtonStyle 


0xE159 

"Save Local" 

SaveLocalAppBarButtonStyle 

□ 

0xE15A 

"Caption" 

CaptionAppBarButtonStyle 

■ 

0xE15B 

■ ， StOD" 

StooADDBarButtonStvIe 


Don’t feel restricted to the items in this list. You can use any character in the Segoe Ul Symbol font 
for application bar buttons, or you can specify a different font. 

Inside the Segoe Ul Symbol Font 

Besides the characters in the private-use area, the Segoe Ul Symbol font also supports character 
codes from 0x2600 through 0x26FF that the Unicode standard classifies as "miscellaneous symbols." 
Some of these characters might also be suitable for application bar buttons. 

The Segoe Ul Symbol font also goes beyond the range of 16-bit codes and contains glyphs for 
character codes 0xlF300 through 0xlF5FF that map to emoji characters. These are icon characters 
that originated in Japan but that have also found their way into the Microsoft Windows Phone and 
the Apple iPhone. 


276 PART: Elementals 





The Segoe Ul Symbol font also supports common emoticon characters in the range 0xlF600 
through 0xlF64F, including nine cat emoticons and a trio of see-no-evil, hear-no-evil, speak-no-evil 
monkeys. 

Also supported is the range from 0xlF680 through 0xlF6C5 containing transportation and map 
symbols. 

To help you (and me) select additional symbols for application bars, I’ve written a program named 
SegoeSymbols that displays all the characters from 0 through OxlFFFF in the Segoe Ul Symbol font. 

As you might know, Unicode started out as a 16-bit character encoding with codes ranging from 
0x0000 through OxFFFF. When it became evident that 65,536 code points were not sufficient, Unicode 
began incorporating character codes in the range 0x10000 through OxlOFFFF, increasing the number 
of characters to over 1.1 million. This expansion of Unicode also included a system to represent these 
additional characters using a pair of 16-bit values. 

The use of a single 32-bit code to represent Unicode characters is known as 32-bit Unicode 
Transformation Format, or UTF-32. But that’s a bit of misnomer because with UTF-32 there is no 
transformation: A one-to-one mapping exists from the 32-bit numeric codes to character glyphs. 

UTF-32 is extremely rare. Indeed, most people don’t even think of Unicode as a 32-bit character 
encoding because the 32-bit part of Unicode is really tacked on to the 16-bit encoding. 

Accordingly, most modern programming languages and operating systems instead support UTF- 
16. The Char structure in the Windows Runtime is basically a 16-bit integer, and that’s the basis for the 
char data type in C#. To represent the additional characters in the range 0x10000 through OxlOFFFF, 
UTF-16 uses two 16-bit characters in sequence. These are known as surrogates, and a special range of 
16-bit codes in Unicode has been set aside for their use. The leading surrogate is in the range 0xD800 
through OxDBFF, and the trailing surrogate is in the range OxDCOO through OxDFFF. That’s 1,024 pos¬ 
sible leading surrogates, and 1,024 possible trailing surrogates, which is sufficient for the 1,048,576 
codes in the range 0x10000 through OxlOFFFF. (You’ll see the actual algorithm shortly.) 

Text in languages that use the Latin alphabet is mostly restricted to ASCII character codes in the 
range 0x0020 and 0x007E, so most webpages and other files save lots of space by using a system 
called UTF-8 for storing text. UTF-8 encodes these 7-bit characters directly but uses one to three 
additional bytes for other Unicode characters. 

Because I wrote SegoeSymbols mostly to let me examine the symbols that might be useful in 
application bars, the program only goes up to character codes of OxlFFFF. The XAML file has a simple 
title, a Grid awaiting rows and columns to display a block of 256 characters, and a Slider: 

Project: SegoeSymbols | File: MainPage.xaml (excerpt) 

<Page … > 

<Page.Resources 〉 

<local : DoubleToStringHexByteConverter x: Key="hexByteConverter" /> 

</Page.Resources 〉 
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<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Grid.RowDefinitions> 

<RowDefinition Hei ght="Auto" /> 

〈RowDefinition Height:"*" /> 

<RowDefinition Hei ght="Auto" /> 

</Grid.RowDefinitions> 


<TextBlock Name="ti tleText" 

Grid.Row= ,, 0" 

Text="Segoe UI Symbol" 

HorizontalAli gnment="Center" 

Style="{Stati cResource HeaderTextStyl e}" /> 

<Grid Name="characterGri d" 

Gn'd.Row="l" 

HorizontalAli gnment="Center" 

VerticalA1i gnment="Center" /> 

<S1ider Grid.Row="2" 

Orientati on="Hori zontal" 

Margin="24 0" 

Minimum= ,, 0 M 
Maximum=" 511" 

SmallChange="l" 

LargeChange="16" 

ThumbToolTipValueConverter="{Stati cResource hexByteConverter}" 
ValueChanged="OnSl iderValueChanged" /> 

</Gri d> 

</Page> 


Notice that the Slider has a Maximum value of 511, which is the maximum character code I want 
to display (OxlFFFF) divided by 256. The DoubleToStringHexByteConverter class referenced in the 
Resources section is similar to one you’ve seen before, but it displays a couple underlines as well to be 
consistent with the screen visuals: 


Project: SegoeSymbols | File: DoubleToStringHexByteConverter.es (excerpt) 

public class DoubleToStringHexByteConverter : IValueConverter 

{ 

public object Convert(object value, Type targetType, object parameter, string language) 

{ 

return ((i nt) (doubl e)value).ToString("X2") + "_" ; 

} 

public object ConvertBack (object value, Type targetType, object parameter, string language) 

{ 

return value; 



Each Slider value corresponds to a display of 256 characters in a 16 x 16 array. The code to build 
the Grid that displays these 256 characters is rather messy because I decided that there should be 
lines between all the rows and columns of characters and that these lines should have their own rows 
and columns in the Grid. 
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Project: SegoeSymbols | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

const int Cell Size = 36; 

const int LineLength = (CellSize + 1) * 16 + 18; 

FontFamily symbol Font = new FontFami1y ("Segoe UI Symbol"); 

TextBlock[] txtblkColumnHeads = new TextB1ock[16] ; 

TextB1ock[,] txtblkCharacters = new TextBlock[16, 16]; 

public MainPageO 

{ 

this .Ini tializeComponent(); 

for (int row = 0; row < 34; row++) 

{ 

RowDefinition rowdef = new RowDefini tion() ; 

if (row == 0 I I row % 2 == 1) 

rowdef.Height = GridLength .Auto; 

else 

rowdef.Height = new GridLength (Cel 1 Size, GridUnitType .Pixel) 

characterGrid.RowDefinitions.Add(rowdef); 

if (row != 0 && row % 2 == 0) 

{ 

TextBlock txtblk = new TextBlock 

{ 

Text = (row / 2 - 1).ToString("Xl"), 

VerticalAlignment = VerticalAl i gnment .Center 

}； 

Grid .SetRow(txtblk, row); 

Grid ■SetColumn(txtblk, 0); 
characterGrid.ChiIdren.Add(txtblk); 


if (row % 2 == 1) 

{ 

Rectangle rectangle = new Rectangle 

{ 

Stroke = this .Foreground, 

StrokeThickness = row == 1 || row == 33 ? 1.5 : 0.5 
Height = 1 

}； 

Grid .SetRow(rectangle, row); 

Grid .SetColumn(rectangle, 0); 

Grid .SetColumnSpan(rectangle, 34); 
characterGrid.ChiIdren.Add(rectangle); 


} 


for (int col = 0; col < 34; col++) 

{ 

ColumnDefinition coldef = new ColumnDefinition (); 
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if (col == 0 I I col % 2 == 1) 

coldef.Width = GridLength .Auto; 

else 

coldef.Width = new Gri dLength(Cel 1 Size); 

characterGrid.ColumnDefinitions.Add(coldef); 

if (col != 0 && col % 2 == 0) 

{ 

TextBlock txtblk = new TextBlock 

{ 

Text = "00" + (col / 2 - 1).ToStri ng("Xl") + 
HoHzontal Alignment = Horizontal A1 ignment .Center 

}； 

Grid.SetRow(txtblk, 0); 

Grid. SetColumn(txtblk, col); 
characterGrid.Children.Add(txtblk); 
txtblkColumnHeads[col / 2 - 1] = txtblk; 


if (col % 2 == 1) 

{ 

Rectangle rectangle = new Rectangle 

{ 

Stroke = this .Foreground, 

StrokeThickness = col == 1 || col == 33 ? 1.5 : 0 
Width = 1 

}； 

Grid .SetRow(rectangle, 0); 

Grid .SetColumn(rectangle, col); 

Grid. SetRowSpan(rectangle, 34); 
characterGrid.Children.Add(rectangle); 

} 

} 


} 


for (i nt col = 0; col < 16; col++) 

for (i nt row = 0; row < 16; row++) 

{ 

TextBlock txtblk = new TextBlock 

{ 

Text = ((char) (16 * col + row)).ToString(), 
FontFamily = symbol Font, 

FontSize = 24, 

HorizontalAlignment = HorizontalATignment .Center, 
Ve rticalA1ignment = Vertical Alignment. Center 

}； 

Grid .SetRow(txtblk, 2 * row + 2); 

GHd ■ SetCol umn (txtbl k，2 * col + 2); 
characterGrid.Children.Add(txtblk); 
txtblkCharacters[col, row] = txtblk; 


} 
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The ValueChanged handler for the Slider has the relatively easier job of inserting the correct text 
into the existing TextBlock elements, but there’s also that irksome matter of dealing with character 
codes above OxFFFF: 

Project: SegoeSymbols | File: MainPage.xaml.es (excerpt) 

void OnSliderValueChanged (object sender, RangeBaseValueChangedEventArgs args) 

{ 

int baseCode = 256 * (int)args .NewValue; 

for (i nt col =0; col < 16; col++) 

{ 

txtblkColumnHeads[col].Text = (baseCode / 16 + col).ToString("X3") + ; 

for (i nt row = 0; row < 16; row++) 

{ 

int code = baseCode + 16 * col + row; 
string strChar = null; 

if (code <= OxOFFFF) 

{ 

strChar = ((char) code).ToString(); 

} 

else 

{ 

code -= 0x10000; 

int lead = 0xD800 + code / 1024; 

int trail = OxDCOO + code % 1024; 

strChar = C(char)lead) .ToString() + (char)trai 1; 

} 

txtblkCharacters[col, row].Text = strChar; 

} 

} 

} 

Four statements toward the end of the handler demonstrate the mathematics that separate a Unicode 
character code between 0x10000 and OxlOFFFF into two 10-bit values to construct leading and trail¬ 
ing surrogates, which together in a string define a single character. 

If you're the type of person who prefers not witnessing how sausage is made, you can replace 
those four lines with 

strChar = Char.ConvertFromUtf32(code); 

For a code value of OxFFFF and below, Char. Con vert From Utf32 returns a string consisting of one 
character; for codes above OxFFFF, the string has two characters. Passing the method a surrogate code 
(0xD800 through OxDFFF) raises an exception. 

The areas that are of most interest in constructing application bar buttons begin at 0x2600 (the 
miscellaneous symbols area), OxElOO (the private use area used by the Seqoe Ul Symbol font), and 
0xlF300 (emoji, emoticons, and transportation and map symbols). Here’s the first screen of the emoji 
characters: 
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Segoe Ul Symbol 


1F30 

1F31_ 

1F32 

1F33 

1F34 

1F35 

1F36 

1F37 

1F38 

1F39 

1F3A 
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1F3F 

xy 


% 
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r? 
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函 
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里 
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b 

□ 
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A 

□ 

□ 

叁 

□ 


You can specify a character beyond OxFFFF in XAML like so: 

〈TextBlock FontFami1 y="Segoe UI Symbol" 

FontSize="24" 

Text="&#xlF3B7;" /> 

That’s the saxophone symbol. Visual Studio sometimes complains, but the program compiles and runs 
just fine. 

Here’s a row of application bar buttons obviously for a very musical application: 

<Button Styl e="{StaticResource AppBarButtonStyl e}" 

Content="&#xlF3B7;" 

AutomationProperties. Name="Saxophone" 

Cli ck="OnMusi cButtonClick" /> 

<Button Styl e="{StaticResource AppBarButtonStyl e}" 

Content="&#xlF3B8 ;" 

AutomationProperties. Name="Gui tar" 

Cli ck="OnMusi cButtonClick" /> 

<Button Styl e="{StaticResource AppBarButtonStyl e}" 

Content="&#xlF3B9; " 

AutomationProperties .Name="Pi ano" 

Cli ck="OnMusi cButtonClick" /> 

<Button Styl e="{StaticResource AppBarButtonStyl e}" 

Content="«&#xlF3BA; " 

AutomationProperties. Name="T rumpet" 

Cli ck="OnMusi cButtonClick" /> 

<Button Styl e="{StaticResource AppBarButtonStyl e}" 

Content= ,, &#xlF3BB;" 

AutomationProperties .Name="Viol in" 

Cli ck="OnMusi cButtonClick" /> 
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And here it is: 
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Saxophone 

Guitar 

Piano 

Trumpet 

Violin 


App Bar CheckBox and RadioButton 

Circular buttons that function like CheckBox or RadioButton can be seen on the application bars of 
several standard Windows 8 applications. In the Calendar application, the Day, Week, and Month 
buttons work like a trio of RadioButton controls, and the Show Traffic button in the Maps application 
works like a CheckBox. 

The AppBarButtonStyle has a TorgetType of ButtonBase, which means that you can use it to style 
a CheckBox ora RadioButton. However, in the version of StandardStyles.xaml that \'rr\ seeing, the 
ControlTemplote for AppBarButtonStyle has a reference to BackgroundCheckedGlyph, which is not 
defined in the template. If you get an error when using these styles with CheckBox or RadioButton, 
comment out the ObjectAnimationUsingKeyFromes object that references BackgroundCheckedGlyph. 

This is what IVe done for the TextFormattingAppBar, which has a Text Block sitting in the center 
of the page with an application bar with three CheckBox controls and three RadioButton controls, all 
with styles based on AppBarButtonStyle: 


Project: TextFormattingAppBar I File: MainPage.xaml (excerpt) 

<Page … > 

<Grid Background="Li ghtGray"> 

<TextBlock Name="textBl ock" 

FontFami1 y="Ti mes New Roman" 
FontSize="96" 

HorizontalAli gnment="Center" 
VerticalAli gnment="Center"> 
<Run>Text Formatting AppBar</Run> 
</TextBlock> 

</Gri d> 


<Page.BottomAppBar> 

<AppBar> 

<StackPanel Orientati on="Hori zontal "> 

cCheckBox Styl e="{StaticResource BoldAppBarButtonStyle}" 
Checked="OnBoldAppBarCheckBoxChecked" 
Unchecked="OnBol dAppBarCheckBoxChecked" /> 

<CheckBox Styl e="{StaticResource ItalicAppBarButtonStyl e}" 
Checked="OnItali cAppBarCheckBoxChecked" 
Unchecked="OnItal icAppBarCheckBoxChecked" /> 

<CheckBox Styl e="{StaticResource UnderlineAppBarButtonStyle} 
Checked="0nllnderl i neAppBarCheckBoxChecked" 
Unchecked="OnUnderl ineAppBarCheckBoxChecked" /> 
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〈Polyline Points="0 12 ， 0 48" 

Stroke="{StaticResource ApplicationForegroundThemeBrush}" 

VerticalAli gnment="Top" /> 

<RadioButton Name=" redRadioButton" 

Style="{StaticResource FontColorAppBarButtonStyle}" 
Foreground="Red" 

AutomationProperties. Name="Red" 
Checked="OnFontColorAppBarRadioButtonChecked" /> 

<RadioButton Style="{StaticResource FontColorAppBarButtonStyle}" 

Foreground="Green" 

AutomationProperties. Name="Green" 

Checked="OnFontCol orAppBarRadioButtonChecked" /> 

<RadioButton Style="{StaticResource FontColorAppBarButtonStyle}" 

Foreground="Bl ue" 

AutomationProperties. Name="Bl ue" 

Checked="OnFontCol orAppBarRadioButtonChecked" /> 

</StackPanel> 

</AppBar> 

</Page.BottomAppBar> 

</Page> 

When such a button is selected, it's displayed in reverse colors, but it doesn't quite work as nicely 
for the RocJioButton indicating color: 


Text Formatting AppBar 



If you have another idea about how to color a selected Check Box or RadioButton, you can always 
make changes to AppBarButtonStyle. 
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The code-behind file is much as you might expect, except that implementing the underline option 
is exceptionally kludgy: 

Project: TextFormattingAppBar I File: MainPage.xaml (excerpt) 

public sealed partial class MainPage : Page 

{ 

public MainPageO 

{ 

this .Ini ti alizeComponent(); 

} 

void OnBoldAppBarCheckBoxChecked (object sender, RoutedEventArgs args) 

{ 

CheckBox chkbox = sender as CheckBox; 

textBlock.FontWeight = (bool)chkbox. IsChecked ? FontWeights.Bold : FontWeights .Normal; 

} 

void OnltalicAppBarCheckBoxChecked(object sender, RoutedEventArgs args) 

{ 

CheckBox chkbox = sender as CheckBox; 

textBlock.FontStyle = (bool) chkbox.IsChecked ? FontStyle. Italic : FontStyle .Normal; 

} 


void OnUnderlineAppBarCheckBoxChecked(object sender, RoutedEventArgs args) 

{ 

CheckBox chkbox = sender as CheckBox; 

Inline inline = textBlock.Iniines[0]; 

if ((bool)chkbox.IsChecked && !(inline is Underline)) 

{ 

Underline underline = new Underli ne() ; 

textBlock.Iniines[0] = underline; 
underline.Iniines.Add(inline); 

} 

else if (! (bool) chkbox.IsChecked && inline is Underline) 

{ 

Underline underline = inline as Underline; 

Run run = underline.Iniines[0] as Run ; 
underline.Inlines.ClearC); 
textBlock.Iniines[0] = run; 

} 

} 

void OnFontColorAppBarRadioButtonChecked (object sender, RoutedEventArgs args) 

{ 

textBlock.Foreground = (sender as RadioButton) .Foreground; 

} 

} 

Styling a CheckBox or RadioButton is not the only way to implement this type of functionality. 
Another approach to mimic a CheckBox is illustrated in the Weather application. When tapped, the 
Button labeled "Change to Celsius” changes to "Change to Fahrenheit.” 

A button on an application bar can also invoke a PopupMenu or Popup. For example, press the 
button with the wrench icon in Windows 8 Internet Explorer. A little popup appears with at least two 
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additional commands: "Find on page" and "View on the desktop." Or try the Map Style button in 
Maps to see two mutually exclusive options "Road View" and "Aerial View" with a check mark indi¬ 
cating the current selection. Or press the Camera Options command in the Camera application. You 
get a popup with combo boxes, a toggle switch, and a link for "More," which displays a larger popup 
dialog. 

Using PopupMenu and Popup with an application bar is very similar to invoking them with a 
right-click: You just need to position them intelligently, as I’ll demonstrate shortly. 

If you sweep your finger on the right side of the screen while an application is running, you’ll 
bring up the standard list of charms: Search, Share, Start, Devices, and Settings. Ill demonstrate in 
Chapter 17, "Share and Print,” how your application can hook into these charms. In particular, the 
Settings button often invokes a list of options that can include About and Help as well as Settings. 
However, some applications include an Options item on the application bar, and the application bar 
can also contain a Settings item. Indeed, StandardStyles.xaml includes a SettingsAppBarButtonStyle 
that displays a gear icon and the word "Settings." How you divide program functionality among these 
items is up to you, but generally you'll use an application bar Options button for items accessed 
more frequently than the Settings and you’ll use the Settings button on the application bar for items 
accessed more frequently than those on the Settings charm. 


An App Bar for a Note Pad 


The PrimitivePad program in Chapter 7 had three buttons at the top of its page labeled "Open,” 
"Save As" and a ToggleButton with "Wrap" alternating with "No Wrap." Let's convert these to 
application bar buttons, as well as implementing the text-wrapping option as a Popup and adding 
buttons to increase and decrease the font size. But I won’t attempt to make the file I/O logic more 
sophisticated. 

Here’s the MainPage.xaml file for AppBarPad: 


Project: AppBarPad I File: MainPage.xaml (excerpt) 

<Page … > 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<TextBox Name="txtbox" 

IsEnabl ed="Fal se" 

FontSize="24" 

AcceptsReturn="True" /> 

</Gri d> 


<Page.BottomAppBar> 

<AppBar> 

<Gri d> 

<StackPanel Orientati on="Hori zontal" 

HorizontalA1i gnment="Left"> 


〈Button Style="{StaticResource FontlncreaseAppBarButtonStyl e} 
Cli ck="OnFontIncreaseAppBarButtonClick" /> 


〈Button Style="{StaticResource FontDecreaseAppBarButtonStyle} 
Cli ck="OnFontDecreaseAppBarButtonClick" /> 
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<Button Style="{StaticResource SettingsAppBarButtonStyle}" 

AutomationProperties. Name="Wrap Option" 

Cli ck="OnWrapOpti onAppBarButtonClick" /> 

</StackPanel > 

<StackPanel Orientati on="Hori zontal" 

HorizontalA1i gnment="Ri ght"> 

<Button Style="{StaticResource OpenFi1eAppBarButtonStyl e}" 

Cli ck="OnOpenAppBarButtonClick" /> 

<Button Style="{StaticResource SaveAppBarButtonStyl e}" 

AutomationProperties. Name="Save As" 

Cli ck="OnSaveAsAppBarButtonClick" /> 

</StackPanel > 

</Grid> 

</AppBar> 

</Page.BottomAppBar> 

</Page> 

Generally, an application bar has some buttons on the left and some on the right. When holding 
a tablet, these are more convenient than buttons in the middle. You can use XAML in a couple ways 
to divide the buttons between left and right. Perhaps the easiest approach is to put two horizontal 
StockPonel elements in a single-cell Grid and align them on the right and left. 

It's recommended that a New (or Add) button be on the far right, and although this program does 
not have a New button, the other file-related buttons should also appear on the right side because 
they are related to New. I supplied a name of "Save As" to replace "Save" for the Button styled with 
the SaveAppBarButtonStyle. 

The program options are on the left: buttons to increase and decrease the font size, and another 
(using a generic SettingsAppBarButtonStyle) for the word-wrap setting. When you sweep your finger 
on the top or bottom of the screen, here’s what you’ll see: 


'Twas brillig, and the slithy toves 
Did gyre and gimble in the wabe: 

All mimsy were the borogoves, 

And the mome raths outgrabe. 

"Beware the Jabberwock, my son! 

The jaws that bite, the claws that catch! 
Beware the Jubjub bird, and shun 
The frumious Bandersnatch!" 

He took his vorpal sword in hand: 

Long time the manxome foe he sought 
So rested he by the Tumtum tree, 

And stood awhile in thought. 
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The program saves user settings (and the content of the Text Box') in response to the Suspending 
event defined by Application. These settings are loaded in the Loaded handler. For convenience, I’ve 
defined both of these as anonymous methods in the Main Page constructor. Also shown here are the 
simple handlers for the font size increase and decrease buttons: 


Project: AppBarPad I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

public MainPageO 

{ 

this. InitializeComponent(); 

// Get local settings object 

ApplicationDataContainer appData = ApplicationData. Current.LocalSettings; 

Loaded += async (sender, args)=> 

{ 

// Load TextBox settings 

if (appData.Values.Contai nsKeyC'TextWrapping")) 

txtbox.TextWrapping = (TextWrappi ng)appData.Values ["TextWrappi ng"] ; 

if (appData.Values.Contai nsKey("FontSize")) 

txtbox.FontSize = (doubl e) appData.Values ["FontSi ze"] ; 

// Load TextBox content 

StorageFolder local Folder = ApplicationData .Current.Local Folder; 

StorageFi1e storageFi1e = await localFolder.CreateFileAsync(" AppBarPad.txt" , 

CreationCol1isionOption .OpenlfExists); 
txtbox.Text = await Fi1elO. ReadTextAsync(storageFile); 

// Enable the TextBox and give it input focus 

txtbox.IsEnabled = true ; 

txtbox.Focus(FocusState.Programmatic); 

}； 

Application .Current.Suspending += async (sender, args)=> 

{ 

// Save TextBox settings 

appData.Values ["TextWrapping"] = (i nt) txtbox.TextWrapping; 
appData.Values ["FontSi ze"] = txtbox.FontSize; 

// Save TextBox content 

SuspendingDeferral deferral = args.SuspendingOperation.GetDeferral(); 

await PathIO .WriteTextAsync ("ms-appdata : ///local/AppBarPad.txt" , txtbox.Text); 

deferral.Comp!ete(); 

}； 

} 


void OnFontlncreaseAppBarButtonClick (object sender, RoutedEventArgs args) 

{ 

ChangeFontSize(l.1); 

} 
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void OnFontDecreaseAppBarButtonCli ck(object sender, RoutedEventArgs args) 


ChangeFontSize(l/l.1); 

} 

void ChangeFontSi ze(doubl e multiplier) 

{ 

txtbox.FontSize *= multiplier; 

} 


When the Button labeled "Wrap Options" is clicked, the program displays a little dialog with 
"Wrap" and "No wrap” items. I’ve defined the layout of this little dialog as a User Control called 
WropOptionsDialog. The XAML file represents the two options with RacJioButton controls: 


Project: AppBarPad I File: WrapOptionsDialog.xaml (excerpt) 


<UserControl … > 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
〈StackPanel Name="stackPanel " 

Margin="24"> 

<RadioButton Content="Wrap" 

Checked="OnRadioButtonChecked"> 

<RadioButton.Tag> 

<TextWrappi ng>Wrap</TextWrappi ng> 

</RadioButton.Tag> 

</RadioButton> 


<RadioButton Content="No wrap" 

Checked="OnRadioButtonChecked"> 
<RadioButton.Tag> 

<TextWrappi ng>NoWrap</TextWrappi ng> 
</RadioButton.Tag> 

</RadioButton> 

</StackPanel> 

</Gri d> 

</UserControl > 


You’ll notice that this Grid has the standard background brush. It needs to have some kind of brush or 
the background will be transparent. I’ve retained a dark theme in this program, so this dialog will have 
a white foreground and black background and hence contrast with the TextBox. 

The code-behind file for the dialog defines a dependency property named TextWropping of type 
TextWrapping. The property-changed handler checks a RadioButton when this property is set, and the 
property is set when a user selects a RadioButton: 

Project: AppBarPad I File: WrapOptionsDialog.xaml.es (excerpt) 

public sealed partial class WrapOptionsDialog : UserControl 

{ 

static WrapOptionsDialog() 

{ 

TextWrappingProperty = DependencyProperty .Regi ster("TextWrappi ng" , 
typeof (TextWrappi ng) , 
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} 


typeof (WrapOptionsDial og) , 

new PropertyMetadata(TextWrapping .NoWrap, OnTextWrappingChanged)); 


public static DependencyProperty TextWrappingProperty { private set; get; } 

public WrapOptionsDialog() 

{ 

this. InitializeComponent(); 

} 

public TextWrapping TextWrapping 

{ 

set { SetValue(TextWrappingProperty, value); } 

get { return (TextWrappi ng)GetValue(TextWrappingProperty); } 

} 

static void OnTextWrappingChanged (DependencyObject obj, 

DependencyPropertyChangedEventArgs args) 

{ 

(obj as WrapOptionsDial og) .OnTextWrappi ngChanged(args); 

} 

void OnTextWrappingChanged (DependencyPropertyChangedEventArgs args) 

{ 

foreach (UIE1 ement chi 1d in stackPanel.Children) 

{ 

RadioButton radioButton = child as RadioButton ; 

radioButton.IsChecked = 

(TextWrappi ng) radioButton.Tag == (TextWrappi ng)args.NewValue; 



void OnRadioButtonChecked(object sender, RoutedEventArgs args) 

{ 

this .TextWrapping = (TextWrappi ng) (sender as RadioButton) .Tag; 

} 

} 

The event handler for the "Wrap Options” application bar button is in the Main Page code-behind 
file. The event handler instantiates a WropOptionsDialog object and initializes its TextWrappi ng prop¬ 
erty from the TextWrapping property of the Text Box. It then defines a binding in code between the 
two TextWrapping properties. This allows the user to see the result of changing this property directly 
in the Text Box. The WropOptionsDialog object is then made a child of a new Popup object: 

Project: AppBarPad | File: MainPage.xaml.es (excerpt) 

void OnWrapOptionsAppBarButtonCli ck(ob ject sender, RoutedEventArgs args) 

{ 

// Create dialog 

WrapOptionsDialog wrapOptionsDialog = new WrapOptionsDialog 

{ 

TextWrapping = txtbox.TextWrapping 

}； 
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// Bind dialog to TextBox 
Binding binding = new Binding 
{ 

Source = wrapOptionsDialog, 

Path = new PropertyPath("TextWrappi ng") , 

Mode = BindingMode .TwoWay 

}； 

txtbox.SetBinding (TextBox .TextWrappingProperty, binding); 


// Create popup 

Popup popup = new Popup 

{ 

Child = wrapOptionsDial og, 
IsLightDismissEnabled = true 


// Adjust "location based on content size 

wrapOpti onsDialog.Loaded += (dialogSender, dialogArgs)=> 

{ 

// Get Button location relative to screen 
Button btn = sender as Button ; 

Point pt = btn.TransformToVisual (nul1 ).TransformPoi nt(new Poi nt(btn.ActualWidth / 2, 

btn.ActualHeight / 2)); 


}； 


popup.HorizontalOffset = pt.X - wrapOptionsDialog.ActualWidth / 2; 
popup.Vertical Offset = thi s .ActualHeight - wrapOptionsDialog.ActualHeight 

- this.BottomAppBar.ActualHeight - 48; 


// Open the popup 
popup.IsOpen = true ; 


Generally, popups such as this are positioned just above the application bar, which means that 
you need to know the height of the popup, the height of the page, and the height of the applica¬ 
tion bar to get it right. I also wanted to position the Popup horizontally so that it’s aligned with the 
button that invoked it. This requires making use of the TronsformToVisuol method (which I’ll discuss in 
Chapter 10, "Transforms") to obtain the coordinates of the center of the button relative to the screen. 
You can perform calculations such as these during either the Loaded or the SizeChonged event on the 
child of the Popup. 
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The Click handler concludes by setting the IsOpen property of the Popup to true, and here it is: 


'Twas brillig, and the slithy toves 
Did gyre and gimble in the wabe: 

All mimsy were the borogoves, 

And the mome raths outgrabe. 

"Beware the Jabberwock, my son! 

The jaws that bite, the claws that catch! 
Beware the Jubjub bird, and shun 
The frumious Bandersnatch!" 


He took his vorpal sword in hand: 

Long tim AJH^Axome foe he sought — 
So rested h«ra^Mumtum tree, 

And stoocRwnTi^n thought. 




The Popup is automatically dismissed when the user taps anywhere outside the Popup, and then 
the user needs to tap once more to dismiss the application bar. Because both AppBar and Popup have 
Opened and Closed events for performing initialization or cleanup, it’s possible to install a handler 
for the Closed event of Popup and use that to set the IsOpen property of the AppBar to false (for 
example). 

The file I/O logic uses the simple static FilelO methods but without exception handling: 


Project: AppBarPad | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 


async void OnOpenAppBarButtonCli ck(object sender, RoutedEventArgs args) 

{ 

Fi1eOpenPicker picker = new Fi1eOpenPi cker() ; 

picker.Fi1eTypeFiIter.Add(" . txt") ; 

StorageFi1e storageFi1e = await picker.PickSingleFileAsync(); 

// If user presses Cancel, result is null 
if (storageFi1e == null) 
return ; 

txtbox.Text = await Fi1elO. ReadTextAsync(storageFile); 

} 

async void OnSaveAsAppBarButtonCli ck(object sender, RoutedEventArgs args) 
{ 

Fi1eSavePicker picker = new Fi1eSavePi cker() ; 

pi cker. DefaultFi1eExtension = ".txt" ; 

picker.Fi1eTypeChoices.Add("Text", new Li st<string> { ".txt" }); 
StorageFi1e storageFi1e = await picker.PickSaveFileAsyncC); 
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// If user presses Cancel, result is null 
if (storageFi1e == null) 
return ; 

await Fi1 elO.WriteTextAsync(storageFi 1e, txtbox.Text); 

} 

} 


Introducing XamICruncher 


Even after becoming familiar with various features of the Windows Runtime, putting it all together to 
create an application can still be a challenge. But with the ability to create application bars and dialog 
boxes, it is now possible to build something that looks like a real application. 


XamICruncher lets you type XAML into a TextBox and see the result. The magic method 
that XamICruncher uses is Xa ml Reader. Load, which you had a brief glimpse of in the 
PathMarkupSyntaxCode project in Chapter 2, "XAML Syntax." The XAML processed by Xa ml Reader 
load cannot reference event handlers or external assemblies, but a tool such as XamICruncher is 
very useful for interactively experimenting with XAML and learning about it. I won’t pretend that this 
program is commercial grade, but it’s a real program with real Windows 8 features. 

Here’s a view of the program with some XAML in the editor on the left and the resultant objects in 
a display area on the right: 



The editor doesn’t include any amenities. It won’t even automatically generate a closing tag when 
you type a start tag; it doesn’t use different colors for elements, attributes, and strings; and it doesn’t 
have anything close to IntelliSense. However, the configuration of the page is changeable: You can put 
the edit window on the top, right, or bottom. 
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The application bar has Add, Open, Save, and Save As buttons as well as a Refresh button and a 
button for application settings: 



You can select whether XamICruncher reparses the XAML with each keystroke or only with a press of 
the Refresh button. That option and others are available from the dialog invoked when you press the 
Settings button: 



I’ve turned on the Ruler and Grid Lines options to show you the result in the display area on the right. 
All these settings are saved for the next time the program is run. 
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Most of the page is a custom UserControl derivative called SplitContainer. In the center is a Thumb 
control that lets you select the proportion of space in the left and right panels (or top and bottom 
panels). In the screen shots, this Thumb is a lighter gray vertical bar in the center of the screen. The 
XAML file for SplitContainer consists of a Grid defined for both horizontal and vertical configurations: 


Project: XamICruncher | File: SplitContainer.xaml 
<UserControl 

x : Cl ass="Xaml Cruncher.SplitContainer" 

xml ns="http: //schemas.microsoft.com/winfx/2006/xaml/presentation" 
xml ns :x="http://schemas.microsoft.com/winfx/2006/xaml" 
xmlns :local="usi ng:XamICruncher"> 


<Grid> 

<!-- Default Orientation is Horizontal --> 

<Grid.ColumnDefinitions> 

<ColumnDefinition x:Name="coldefl" Width="*" MinWidth="100" /> 
<ColumnDefinition Wi dth="Auto" /> 

<ColumnDefi niti on x:Name="coldef2" Width="*" MinWi dth="100" /> 
</Grid.ColumnDefi niti ons> 

<!-- Alternative Orientation is Vertical --> 

<Grid.RowDefini ti ons> 

<RowDefinition x:Name="rowdefl" Height="*" /> 

< RowDefinition Height="Auto" /> 

〈RowDefinition x:Name="rowdef2" Height="0" /> 

</Grid.RowDefinitions> 

<Grid Name="gri dl" 

Grid.Row="0 M 

Grid.Col umn="0" /> 

<Thumb Name="thumb" 

Grid.Row= ,, 0" 

Grid.Col umn="l" 

Width="12" 

DragStarted="OnThumbDragStarted" 

DragDel ta="OnThumbDragDelta" /> 

〈Grid Name="gri d2" 

Grid.Row="0" 

Grid.Column="2" /> 

</Gri d> 

</UserControl> 


In Chapter 5 you’ve seen similar markup in the OrientableColorScroll program, which altered a Grid 
when the aspect ratio of the page changed between landscape and portrait. 
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The code-behind file defines five properties backed by dependency properties. Normally the 
Childl and Child2 properties are set to the elements to appear in the left and right of the control, but 
where they actually appear is governed by the Orientation and SwapChildren properties: 


Project: XamICruncher I File: SplitContainer.xaml.es (excerpt) 

public sealed partial class SplitContainer : UserControl 

{ 

// Static constructor and properties 
static SplitContainer() 

{ 

ChiIdlProperty = 

DependencyProperty .Register("Chi Idl" , 

typeof (UIE1ement) , typeof (Spl itContai ner) , 
new PropertyMetadata(nul 1 , OnChiIdChanged)); 


Child2Property = 

DependencyProperty .Regi ster("Chi ld2" , 

typeof CUIE1ement) , typeof (Spl itContai ner ) ， 
new PropertyMetadataCnul 1 , OnChiIdChanged)); 


OrientationProperty = 

DependencyProperty .Regi ster("Ori entation" , 

typeof (Ori entati on) , typeof (Spl itContai ner) , 

new PropertyMetadataCOrientation .Horizontal, OnOrientationChanged)); 


SwapChildrenProperty = 

DependencyProperty .Regi ster("SwapChi ldren" , 
typeof(bool ), typeof (Spl itContai ner ) ， 
new PropertyMetadata(fal se , OnSwapChildrenChanged)); 


MinimumSizeProperty = 

DependencyProperty .Regi ster("Mi nimumSize" , 
typeof(doubl e) , typeof (Spl itContai ner ) ， 
new PropertyMetadata(100 .0, OnMinSizeChanged)); 


pub!ic 
public 
pub!ic 
public 
public 


static DependencyProperty ChiIdlProperty { private set ; get; } 
static DependencyProperty Child2Property { private set ; get; } 


static DependencyProperty OrientationProperty { private set; get; } 
static DependencyProperty SwapChildrenProperty { private set; get; } 
static DependencyProperty Mi nimumSizeProperty { private set; get; } 


// Instance constructor and properties 
public SplitContainer() 

{ 

this. InitializeComponent(); 

} 


public UIE1ement Childl 

{ 

set { SetValue(ChiIdlProperty, value); } 

get { return (UIElement)GetValue(ChiIdlProperty); } 

} 
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public UIE1ement Child2 
{ 

set { SetValue(Child2Property, value); } 

get { return (UIE1ement) GetValue(Chi1d2Property); } 

} 

public Orientation Orientation 
{ 

set { SetValue(OrientationProperty, value); } 

get { return (Ori entati on)GetValue(OrientationProperty); } 

} 

public bool SwapChildren 
{ 

set { SetValue(SwapChi1drenProperty, value); } 
get { return (bool )GetValue(SwapChi1drenProperty); } 

} 

public double MinimumSize 
{ 

set { SetValue(MinimumSizeProperty, value); } 

get { return (doubl e)GetValue(MinimumSizeProperty); } 



The Orientation property is of type Orientation, the same enumeration used for StockPonel and 
VariobleSizedWropGrid. It’s always nice to use existing types for dependency properties rather than 
inventing your own. Notice that the MinimumSize is of type double and hence is initialized as 100.0 
rather than 100 to prevent a type mismatch at run time. 

The property-changed handlers show two different approaches that programmers use 
in calling the instance property-changed handler from the static handler. I’ve already shown 
you the approach where the static handler simply calls the instance handler with the same 
DependencyPropertyChangedEventArgs object. Sometimes — as with the handlers for the Orientation, 
SwapChildren, and MinimumSize properties — it’s more convenient for the static handler to call the 
instance handler with the old value and new value cast to the proper type: 

Project: XamICruncher I File: SplitContainer.xaml.es (excerpt) 

public sealed partial class SplitContainer : UserControl 
{ 

// Property-changed handlers 

static void OnChi1dChanged(DependencyObject obj, 

DependencyPropertyChangedEventArgs args) 

{ 

(obj as SplitContai ner) .OnChildChanged(args); 

} 
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void OnChildChanged (DependencyPropertyChangedEventArgs args) 

{ 

Crid targetGrid = (args.Property == Chi 1dlProperty 八 this .SwapChi1dren) ? gridl : grid2; 
targetGrid.Children.Clear(); 


if (args.NewValue != null) 

targetGrid.Chi 1dren.Add(args.NewValue as UIE1 ement) ; 


static void OnOrientationChangedCDependencyObject obj ， 

DependencyPropertyChangedEventArgs args) 

{ 

(obj as SplitContai ner) .OnOrientationChanged((Ori entati on)args.OldValue, 

(Ori entati on)args.NewValue); 

} 


void OnOrientationChanged(Ori entation oldOrientation, Orientation newOrientation) 

{ 

// Shouldn't be necessary, but … 
if (newOrientation == oldOrientation) 
return ; 


if (newOrientation == Orientation .Horizontal) 

{ 

coldefl.Width = rowdefl.Height; 
coldef2.Width = rowdef2.Height; 

coldefl.MinWidth = this. MinimumSize; 
coldef2.MinWidth = this. MinimumSize; 

rowdefl.Height = new Gri dLength(l, GridllnitType .Star); 
rowdef2.Height = new Gri dLength(O) ; 

rowdefl.MinHeight = 0; 
rowdef2.MinHeight = 0; 

thumb.Width = 12; 
thumb.Height = Double. NaN; 

Grid .SetRow(thumb, 0); 

Grid. SetColumn(thumb, 1); 

Grid .SetRow(grid2, 0); 

Gri d. SetColumn(grid2, 2); 

} 

else 

{ 

rowdefl.Height = coldefl.Width; 
rowdef2.Height = coldef2.Width; 

rowdefl.MinHeight = this. MinimumSize; 
rowdef2.MinHeight = this. MinimumSize; 


coldefl.Width = new GridLength(l, GridUnitType .Star); 
coldef2.Width = new Gri dLength(O) ; 
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coldefl.MinWidth = 0; 
coldef2.MinWidth = 0; 

thumb.Height = 12; 
thumb.Width = Double. NaN; 

Grid. SetRow(thumb ， 1); 
Grid. SetColumn(thumb, 0); 


Grid.SetRow(grid2, 2); 
Grid. SetColumn(grid2, 0); 



static void 


(obj as 


} 


OnSwapChildrenChanged(DependencyObject obj, 

DependencyPropertyChangedEventArgs args) 

SplitContai ner). OnSwapChi1drenChanged ((bool )args.01dValue, 

(bool)args.NewValue); 


void OnSwapChi"! drenChanged (bool oldOrientation, bool newOri entati on) 

{ 

gridl.Children.Cl ear(); 
grid 2 .Children.Cl ear(); 

gridl.Chi Idren.Add(newOrientation ? this .Child2 : this .Childl); 
grid2.Chi 1dren.Add(newOrientation ? this .Childl : this.Child2) ; 


static void OnMinSizeChanged (DependencyObject obj, 

DependencyPropertyChangedEventArgs args) 


} 


(obj as SplitContai ner) .OnMinSizeChanged ((doubl e)args.OldValue, 

(doubl e)args.NewValue); 


void OnMinSizeChanged (doubl e oldValue, double newValue) 

{ 

if (thi s .Ori entati on == On. entati on .Horizontal) 

{ 

coldefl.MinWidth = newValue; 
coldef2.MinWidth = newValue; 

} 

else 

{ 

rowdef1.MinHeight = newValue; 
rowdef2.MinHeight = newValue; 

} 


} 


My original version of the property-changed handler for Orientation assumed that the Orientation 
property was actually changing, as should be the case whenever a property-changed handler is 
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called. However, I discovered that sometimes the property-changed handler was called when the 
property was set to its existing value. 

All that’s left for SplitContoiner is examining the event handlers for the Thumb. The idea here is 
that the two columns (or rows) of the Grid are allocated size based on the star specification so that 
the relative size of the columns (or rows) remains the same when the size or aspect ratio of the Grid 
changes. However, to keep the Thumb dragging logic reasonably simple, it helps if the numeric 
proportions associated with the star specifications are actual pixel dimensions. These are initialized in 
the OnThumbDragStorted method and changed in OnDragThumbDelta: 


Project: XamICruncher I File: SplitContainer.xaml.es (excerpt) 

public sealed partial class SplitContainer : UserControl 


// Thumb event handlers 

void OnThumbDragStarted (object sender, DragStartedEventArgs args) 

{ 

if (this .Orientation == Orientation .Horizontal) 

{ 

coldefl.Width = new Gri dLength(coldefl.ActualWidth, GridUnitType .Star); 
coldef2.Width = new GridLength (coldef2.ActualWidth, GridUnitType .Star); 

} 

else 

{ 

rowdefl.Height = new Gri dLength(rowdefl.ActualHeight, GridUnitType .Star); 
rowdef2.Height = new GridLength (rowdef2.ActualHeight, GridUnitType .Star); 

} 


void OnThumbDragDel ta(object sender, DragDeltaEventArgs args) 

{ 

if (this .Orientation == Orientation .Horizontal) 

{ 

double newWidthl = Math .Max(0, coldefl.Width.Value + args.HorizontalChange); 
double newWidth2 = Math .Max(0, coldef2.Width.Value - args.Horizontal Change); 


coldefl.Width = new Gri dLength(newWi dthl, GridUnitType. Star); 
coldef2.Width = new Gri dLength(newWi dth2, GridUnitType. Star); 

} 

else 


double newHeightl = Math. Max(0, rowdefl.Height.Value + args.VerticalChange); 
double newHeight2 = Math. Max(0, rowdef2.Height.Value - args.VerticalChange); 


rowdefl.Height = new GridLength (newHeightl, GridUnitType .Star); 
rowdef2.Height = new GridLength (newHeight2, GridUnitType .Star); 



The last of the earlier screen shots of XamICruncher showed a ruler and grid lines in the display 
area. The ruler is in units of inches, based on 96 pixels to the inch, so the grid lines are 24 pixels apart. 
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The ruler and grid lines are useful if you're interactively designing some vector graphics or other 
precise layout. 

The ruler and grid lines are independently optional. The User Control derivative that displays them 
is called RulerContoiner. As you’ll see when the XamICruncher page is constructed, an instance of 
RulerContoiner is set to the Chi Id2 property of the SplitContoiner object. Here's the XAML file for 
RulerContoiner. 


Project: XamICruncher I File: RulerContainer.xaml (excerpt) 
<UserControl … > 

<Grid Si zeChanged="OnGri dSizeChanged"> 
<Canvas Name=" rulerCanvas" /> 

<Grid Name="i nnerGrid"> 

<Grid Name="gri dLinesGrid" /> 
〈Border Name="border" /> 

</Grid> 

</Grid> 

</UserControl > 


This RulerContoiner control has a Child property, and the child of this control is set to the Child 
property of the Border. Visually behind this Border is the grid of horizontal and vertical lines, which 
are children of the Grid labeled "gridLinesGrid.” If the ruler is also present, the Grid labeled "innerGrid" 
is given a nonzero Margin on the left and top to accommodate this ruler. The tick marks and numbers 
that comprise the ruler are children of the Canvas named "rulerCanvas.” 

Here’s all the overhead for the dependency property definitions in the code-behind file: 

Project: XamICruncher I File: RulerContainer.xaml.es (excerpt) 

public sealed partial class RulerContainer : UserControl 


static RulerContainer() 

{ 

ChildProperty = 

DependencyProperty .Regi ster("Chi Id" , 

typeof (UIE1 ement) , typeof (Rul erContai ner ) ， 
new PropertyMetadata(nul1 , OnChi1dChanged)); 

ShowRulerProperty = 

DependencyProperty .Regi ster("ShowRul er" , 
typeof (bool) , typeof (Rul erContai ner) , 
new PropertyMetadata(fal se , OnShowRulerChanged)); 

ShowGridLinesProperty = 

DependencyProperty. Regi ster("ShowGri dLines" , 
typeof (bool) , typeof (Rul erContai ner) , 
new PropertyMetadata(fal se , OnShowGridLinesChanged)); 

} 

public static DependencyProperty ChildProperty { private set; get; } 
public static DependencyProperty ShowRulerProperty { private set; get; } 
public static DependencyProperty ShowGridLinesProperty { private set ; get; } 
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public RulerContainer() 

{ 

this. InitializeComponentO ; 

} 

public UIE1ement Child 

{ 

set { SetValue(ChildProperty, value); } 

get { return (UIE1ement) GetValue(ChildProperty); } 

} 

public bool ShowRuler 

{ 

set { SetValue(ShowRulerProperty, value); } 
get { return (bool )GetValue(ShowRulerProperty); } 

} 


public bool ShowGridLines 

{ 

set { SetValue(ShowGridLinesProperty, value); } 
get { return (bool )GetValue(ShowGridLinesProperty); } 

} 


// Property 
static void 

{ 


changed handlers 

OnChi1 dChanged(DependencyObject obj, 

DependencyPropertyChangedEventArgs args) 


(obj as RulerContai ner) .border.Chi Id = (UIElement)args.NewValue; 

} 


static void 

{ 


OnShowRulerChanged(DependencyObject obj, 

DependencyPropertyChangedEventArgs args) 


(obj as Rul erContai ner) . RedrawRulerO ; 

} 


static void 

{ 


OnShowGridLi nesChanged(DependencyObject obj, 

DependencyPropertyChangedEventArgs args) 


(obj as RulerContai ner) .RedrawGridLines(); 

} 


void OnGridSi zeChanged(object sender, SizeChangedEventArgs args) 

{ 

RedrawRulerO ； 

RedrawGridLines(); 

} 


} 
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Also shown here are the property-changed handlers (which are simple enough to use in the static 
versions) as well as the SizeChonged handler for the Grid. Two redraw methods handle all the drawing, 
which involves creating Line elements and TextBlock elements and organizing them in the two panels: 


Project: XamICruncher I File: RulerContainer.xaml.es (excerpt) 

public sealed partial class RulerContainer : UserControl 

{ 

const double RULER_WIDTH = 12; 

void RedrawGridLines() 

{ 

gridLinesGrid.Children.Clear(); 

if (! this .ShowGridLines) 
return ; 


// Vertical grid lines every 1/4" 

for (double x = 24; x < gridLinesGrid.ActualWidth; x += 24) 

{ 

Line line = new Line 

{ 

XI = x, 

Y1 = 0, 

X2 = x, 

Y2 = gridLinesGrid.Actual Height, 

Stroke = this .Foreground, 

StrokeThickness = x % 96 == 0 ? 1 : 0.5 

}； 

gri dLinesGrid.Children.Add(line); 


// Horizontal grid lines every 1/4" 

for (double y = 24; y < gridLinesGrid.ActualHeight; y += 24) 

{ 

Line line = new Line 

{ 

XI = 0, 

Yi = y, 

X2 = gridLinesGrid.ActualWidth, 

Y2 = y, 

Stroke = this .Foreground, 

StrokeThickness = y % 96 == 0 ? 1 : 0.5 

}； 

gri dLinesGrid.Children.Add(line); 



void RedrawRuler() 

{ 

rulerCanvas.Children.Cl ear(); 

if (Ithis.ShowRuler) 

{ 

innerGrid.Margin = new Thickness (); 
return ; 

} 

innerGrid.Margin = new Thickness (RULER_WIDTH, RULER_WIDTH, 0, 0); 
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// Ruler across the top 

for (double x = 0; x < gridLinesGrid.ActualWidth - RULER—WIDTH; x += 12) 

{ 

// Numbers every inch 
if (x > 0 && x % 96 == 0) 

{ 

TextBlock txtblk = new TextBlock 

{ 

Text = (x / 96).ToString("F0"), 

FontSize = RULER_WIDTH - 2 

}； 


txtblk.Measure (new Si ze()); 

Canvas .SetLeft(txtblk, RULER_WIDTH + x - txtblk.ActualWidth / 2); 
Canvas .SetTopCtxtblk, 0); 
rulerCanvas.Chi Idren.Add(txtblk); 

} 

// Tick marks every 1/8" 
else 
{ 

Line line = new Line 

{ 

XI = RULER_WIDTH + x, 

Y1 = x % 48 == 0 ? 2 : 4, 

X2 = RULER_WIDTH + x, 

Y2 = x % 48 == 0 ? RULER_WIDTH - 2 : RULER_WIDTH - 4, 

Stroke = this. Foreground, 

StrokeThickness = 1 

}； 

rulerCanvas•Children.Add(1ine); 



// Heavy line underneath the tick marks 
Line topLine = new Line 
{ 

XI = RULER_WIDTH - 1, 

Y1 = RULER_WIDTH - 1, 

X2 = rulerCanvas.ActualWidth, 

Y2 = RULER—WIDTH - 1 ， 

Stroke = this .Foreground, 

StrokeThickness = 2 

}； 

rulerCanvas.Chi Idren.Add(topLine); 

// Ruler down the "left side 

for (double y = 0; y < gridLinesGrid.Actual Height - RULER_WIDTH; y += 12) 

{ 

// Numbers every inch 
if (y > 0 && y % 96 == 0) 

{ 

TextBlock txtblk = new TextBlock 

{ 

Text = (y / 96).ToString( ,, F0 M ), 

FontSize = RULER_WIDTH - 2, 

}； 
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txtbl k. Measure (new SizeQ); 


Canvas .SetLeft(txtblk, 2); 

Canvas. SetTop(txtblk, RULER_WIDTH + y - txtblk.Actual Height / 2); 
rulerCanvas.Chi Idren.Add(txtbl k); 

} 

// Tick marks every 1/8" 
else 
{ 

Line line = new Line 
{ 

XI = y % 48 == 0 ? 2 : 4, 

Y1 = RULER_WIDTH + y, 

X2 = y % 48 == 0 ? RULER_WIDTH - 2 : RULER_WIDTH - 4, 

Y2 = RULER—WIDTH + y, 

Stroke = this .Foreground, 

StrokeThickness = 1 


}； 

rulerCanvas.Children.Add(li ne); 


Line leftLine = new Line 
{ 

XI = RULER_WIDTH - 1, 

Y1 = RULER_WIDTH - 1, 

X2 = RULER_WIDTH - 1, 

Y2 = rulerCanvas.ActualHeight, 

Stroke = this .Foreground, 
StrokeThickness = 2 

}； 

rulerCanvas.Chi 1dren.Add(1 eftLine); 



These two methods make extensive use of the Line element, which renders a single straight line 
between the points (XI, Yl) and (X2, Y2). 

This RedrawRuler code also illustrates a technique for obtaining the rendered size of a Text Block: 
When you create a new TextBlock, the Actual Width and ActualHeight properties are both zero. 

These properties are normally not calculated until the Text Block becomes part of a visual tree and is 
subjected to layout. However, you can force the TextBlock to calculate a size for itself by calling its 
Measure method. This method is defined by UlElement and is an important component of the layout 
system. 

The argument to the Measure method is a Size value indicating the size available for the element, 
but you can set the size to zero for this purpose: 


txtblk.Measure(new SizeQ); 


If you need to find the size of a TextBlock that wraps text, you must supply a nonzero first argument 
to the Size constructor so that TextBlock knows the width in which to wrap the text. 
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Following the Measure call, the Actual Width and ActuolHeight properties of TextBlock are valid 
and usable for positioning the TextBlock in a Canvas. Calling the Canvas.SetLeft and Canvas.SetTop 
properties is necessary only when positioning the TextBlock elements in the Canvas. In either a single¬ 
cell Grid or Canvas, the Line elements are positioned based on their coordinates. 

As you’ll see, an instance of RulerContoiner is set to the Child2 property of the SplitContainer that 
dominates the XamICruncher page. The Childl property appears to be a TextBox, but it’s actually an 
instance of another custom control named TobbobleTextBox, which derives from TextBox. 

The standard TextBox does not respond to the Tab key, and when you're typing XAML into an 
editor, you really want tabs. That's the primary feature of TabbobleTextBox, shown here in its entirety: 


Project: XamICruncher I File: TabbableTextBox.es 

using Windows.System; 
using Windows.UI.Xaml; 
using Windows.UI.Xaml.Controls; 
using Windows.UI.Xaml.Input; 


namespace XamICruncher 

{ 

public cl ass TabbableTextBox : TextBox 

{ 

static TabbableTextBox() 

{ 

TabSpacesProperty = 

DependencyProperty .Regi ster("TabSpaces" , 
typeof (int) , typeof (TabbableTextBox) , 
new PropertyMetadata(4)) ; 

} 

public static DependencyProperty TabSpacesProperty { private set ; get; } 

public int TabSpaces 

{ 

set { SetValue(TabSpacesProperty, value); } 
get { return (int)GetValue(TabSpacesProperty); } 

} 

public bool IsModified { set ; get; } 

protected override void OnKeyDown (KeyRoutedEventArgs args) 

{ 

this .IsModified = true ; 

if (args.Key == VirtualKey .Tab) 

{ 

int line, col; 

GetPositionFromIndex(thi s .SelectionStart, out line, out col); 

int insertCount = this .TabSpaces - col % this .TabSpaces; 

this. SelectedText = new stri ng( ' ' , insertCount); 

this. SelectionStart += insertCount; 

this .SelectionLength =0; 

args.Handled = true; 

return ; 
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} 


base .OnKeyDown(args); 


public void GetPositionFromIndex(i nt index, out int line, out int col) 
{ 

if (index > Text.Length) 

{ 

line = col = -1; 
return ; 

} 

line = col =0; 
int i = 0; 

while (i < index) 

{ 

if (Text[i] == '\n') 

{ 

1ine++; 
col = 0; 

} 

else if (Text[i] == '\r') 

{ 

index++; 

} 

else 

{ 

col++; 

}； 

i++: 


} 


} 

The class intercepts the OnKeyDown method to determine if the Tab key is being pressed. If that’s 
the case, it inserts blanks into the Text object so that the cursor moves to a text column that is an 
integral multiple of the TabSpaces property. This calculation requires knowing the character position 
of the cursor on the current line. To obtain this information, it uses the G etPositionFromlndex method 
also defined in this class. (Although the lines in the Text property of the TextBox are delimited by 
a carriage return and line feed, the SelectionStart index is calculated based on just one end-of-line 
character.) This method is public and is also used by XamICruncher to display the current position of 
the cursor and the current selection (if any). 

Another property — not backed by a dependency property — is also defined by TabbableTextBox. 
This is IsModified, which is set to true whenever a Key Down event occurs. 

Like many programs that deal with documents, XamICruncher keeps track if the text file has 
changed since the last save. If the user initiates an operation to create a new file or open an existing 
file, and the current document is in a modified state, the program asks if the user wants to save that 
document. 
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Often this logic occurs entirely external to the TextBox control. The program sets an IsModifiecJ flag 
to false when a new file is loaded or the file is saved and to true on receipt of a TextChonged event. 
However, the TextChonged event is fired when the Text property of the TextBox is set programmati¬ 
cally, so even if the TextBox is being set to a newly loaded file, the TextChonged event is fired and the 
IsModifiecJ flag would be set by the TextChonged handler. You might think that setting the IsModified 
flag in that case might be avoided by setting a flag when the Text property is set programmatically. 
However, the TextChonged handler is not called until the method setting the Text property has 
returned control to the operating system, which makes the logic rather messy. Implementing the 
IsModified flag in the TextBox derivative helps. 


Application Settings and View Models 

Many applications maintain user settings and preferences between invocations of the program. As 
you’ve seen, the Windows Runtime provides an isolated area of application data storage for storing 
settings or entire files. 

In this program, I’ve consolidated user settings in a class named AppSettings. This class implements 
INotifyPropertyChangecJ to let it be used for data binding. It’s basically a View Model, or perhaps (in a 
larger application) part of a View Model. 

One program option that should be saved is the orientation of the edit and display areas. As 
you’ll recall, the SplitContoiner has two properties named Orientation and SwapChildren. For stor¬ 
ing user settings, I wanted something more specific to this application. The TextBox (or rather, the 
TabbobleTextBox) can be on the left, top, right, or bottom, and this enumeration encapsulates those 
options: 


Project: XamICruncher I File: EditOrientation.es 

namespace XamICruncher 
{ 

public enum EditOrientation 
{ 

Left, Top, Right, Bottom 

} 

} 


Here’s AppSettings showing all the properties that comprise program settings. The constructor 
loads the settings, and a Save method saves them. All the property values are backed by fields initial¬ 
ized with the program’s default settings. Notice that the EditOrientation property is based on the 
EditOrientotion enumeration: 


Project: XamICruncher I File: AppSettings.es 

public class AppSettings : INotifyPropertyChanged 
{ 

// Application settings initial values 
EditOrientation editOrientation = EditOrientation .Left; 
Orientation orientation = Orientation. Horizontal; 
bool swapEditAndDisplay = false; 


308 PART Elementals 



bool autoParsing = false; 
bool showRuler = false; 
bool showGridLines = false; 
double fontSize = 18; 
int tabSpaces =4; 


public event PropertyChangedEventHandler PropertyChanged; 


public AppSettings() 

{ 

ApplicationDataContainer appData = ApplicationData. Current.LocalSettings; 

if (appData.Values.Contai nsKey("Edi tOrientati on")) 

this .EditOrientation = (Edi tOrientati on) (i nt) appData.Values [ M EditOrientati on"] ; 

if (appData.Values.Contai nsKey("AutoParsing")) 

this .AutoParsing = (bool )appData.Values ["AutoParsing"] ; 

if (appData.Values.Contai nsKey("ShowRul er")) 

this. ShowRuler = (bool) appData.Values ["ShowRuler"] ; 

if (appData.Values.Contai nsKeyC'ShowGri dLines")) 

thi s . ShowGri dLi nes = (bool)appData.Values["ShowGn'dLi nes"] ; 

if (appData.Values.Contai nsKey("FontSize")) 

this ■FontSize = (double) appData.Values ["FontSize"] ; 

if (appData.Values.ContainsKey ("TabSpaces")) 

this .TabSpaces = (i nt) appData.Values ["TabSpaces"] ; 

} 

public EditOrientation EditOrientation 

{ 

set 

{ 

if (SetProperty<Edi tOrientati on>(ref editOrientation, value)) 

{ 

switch (editOrientation) 

{ 

case EditOrientation. Left : 

this .Orientation = Orientation. Horizontal; 

this .SwapEditAndDisplay = false; 

break; 

case EditOrientation .Top: 

this .Orientation = Orientation .Vertical; 
this .SwapEditAndDisplay = false; 
break; 

case EditOrientation .Right: 

this .Orientation = Orientation .Horizontal; 

this .SwapEditAndDisplay = true; 

break; 
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case EditOrientation .Bottom : 

this .Orientation = Orientation .Vertical; 
this.SwapEditAndDi splay = true; 
break; 

} 

} 

} 

get { return editOrientation; } 

} 

public Orientation Orientation 

{ 

protected set { SetProperty<Ori entati on>(ref orientation, value); } 
get { return orientation; } 

} 

public bool SwapEditAndDisplay 

{ 

protected set { SetProperty<bool>(ref swapEditAndDisplay, value); } 
get { return swapEditAndDisplay; } 


public bool AutoParsing 

{ 

set { SetProperty<bool >(ref autoParsing ， value); } 
get { return autoParsing; } 

} 

public bool ShowRuler 

{ 

set { SetProperty<bool >(ref showRuler, value); } 
get { return showRuler; } 

} 

public bool ShowGridLines 

{ 

set { SetProperty<bool >(ref showGridLines, value); } 
get { return showGridLines; } 

} 

public double FontSize 

{ 

set { SetProperty<doubl e>(ref fontSize, value); } 
get { return fontSize; } 

} 


public int TabSpaces 

{ 

set { SetProperty<i nt>(ref tabSpaces, value); } 
get { return tabSpaces; } 

} 


public void Save() 

{ 

ApplicationDataContainer appData = ApplicationData. Current.LocalSettings; 
appData.Values.ClearC); 
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appData.Values.Add("Edi tOrientation" , (i nt)this .EditOrientation); 

appData.Values. Add("AutoParsi ng" , this .AutoParsing); 

appData.Values .Add("ShowRuler" , this. ShowRuler); 

appData.Values. Add("ShowGri dLines" , this .ShowGridLines); 

appData.Values. Add("FontSi ze" , this .FontSize); 

appData.Values. Add("TabSpaces" , this .TabSpaces); 


protected bool SetProperty<T>(ref T storage, T value, 

[Cal 1 erMemberName] string propertyName = null) 

{ 

if (object. Equals(storage, value)) 
return false; 

storage = value; 

OnPropertyChanged(propertyName); 
return true; 

} 

protected void OnPropertyChanged(stri ng propertyName) 

{ 

if (PropertyChanged != null) 

PropertyChanged(thi s , new PropertyChangedEventArgs (propertyName)); 

} 

} 

Besides EditOrientotion, AppSettings defines two additional properties that more directly 
correspond to properties of the SplitContoiner: Orientation and SwopEditAndDisploy. The set accessors 
are protected, and the properties are set only from the set accessor of EditOrientation. These 
two properties are not saved with the other application settings, but they are easily derived from 
application settings and make the bindings easier. 


The XamICruncher Page 


Sufficient pieces have now been created to let us begin assembling this application. Here’s 
MainPage.xaml: 


Project: XamICruncher | File: MainPage.xaml (excerpt) 

<Page … > 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Grid.RowDefinitions> 

〈RowDefinition Height="Auto" /> 

〈RowDefinition Height="*" /> 

< RowDefinition Hei ght="Auto" /> 

</Grid.RowDefiniti ons> 

<Grid.ColumnDefini tions> 

<ColumnDefinition Width="*" /> 

<ColumnDefinition Wi dth="Auto" /> 

</Grid.ColumnDefi nitions> 
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<TextBlock Name="fi 1enameText" 

Grid.Row= ,, 0" 

Grid.Col umn="0" 

Grid.ColumnSpan="2" 

FontSize="18" 

TextTrimmi ng="WordEl 1 i psis" /> 

<local : SplitContainer x : Name="spl itContainer" 

Orientati on="{Bi nding Orientation}" 

SwapChildren="{Bi nding SwapEditAndDisplay}" 

MinimumSi ze="200" 

Grid.Row="l" 

Grid.Column="0" 

Grid.ColumnSpan="2"> 

<1 ocal : SplitContainer.Chi 1dl> 

<local : TabbableTextBox x:Name="edi tBox" 

Accept sReturn="True" 

FontSi ze="{Binding FontSi ze}" 

TabSpaces="{Bi nding TabSpaces}" 
TextChanged="OnEdi tBoxTextChanged" 

Selecti onChanged="OnEdi tBoxSelectionChanged"/> 
</local : SplitContainer.Childl> 

<local : SplitContainer.Chi 1 d2> 

<local : RulerContainer x : Name="resul tContainer" 

ShowRul er="{Binding ShowRuler}" 

ShowGridLi nes="{Bi nding ShowGridLi nes}" /> 
</local : SplitContainer.Child2> 

</local : SplitContainer> 


<TextBlock Name="statusText" 
Text="OK" 

Grid.Row="2" 

Grid.Col umn="0" 

FontSi ze="18" 
TextWrappi ng="Wrap" /> 

<TextBlock Name="l ineColText" 
Grid.Row="2" 

Grid.Col umn="l" 

FontSi ze="18" /> 

</Gri d> 


<Page.BottomAppBar> 

<AppBar> 

<Gri d> 

<StackPanel Orientati on="Hori zontal" HorizontalAli gnment="Left"> 
<Button Style="{StaticResource RefreshAppBarButtonStyl e}" 

Cli ck="OnRef reshAppBarButtonClick" /> 

<Button Style="{StaticResource SettingsAppBarButtonStyle}" 

Cli ck="OnSetti ngsAppBarButtonClick" /> 

</StackPanel> 
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<StackPanel Orientati on="Hori zontal" HorizontalAli gnment="Ri ght"> 
<Button Style="{StaticResource OpenAppBarButtonStyl e}" 

Cli ck="OnOpenAppBarButtonClick" /> 


<Button Style="{StaticResource SaveLocalAppBarButtonStyl e} 
AutomationProperties. Name="Save As" 

Cli ck="OnSaveAsAppBarButtonClick" /> 


〈Button Style="{StaticResource SaveAppBarButtonStyl e} 
Cli ck="OnSaveAppBarButtonClick" /> 


<Button Style="{StaticResource AddAppBarButtonStyle} 
Cli ck="OnAddAppBarButtonClick" /> 
</StackPanel > 

</Grid> 

</AppBar> 

</Page.BottomAppBar> 

</Page> 


The main Grid has three rows: 

■ for the name of the loaded file (the TextBlock named "filenameText ”)， 

■ the SplitContainer, 

■ and the status bar at the bottom. 

The status bar consists of two TextBlock elements named "statusText” (to indicate possible XAML 
parsing errors) and "lineColText" (for the line and column of the TabbableTextBox). The Grid is further 
divided into two columns for the two components of that status bar. 

Most of the page is occupied by the SplitContoiner, and you’ll see that it contains bindings to 
the Orientation and Swap Ed itAnd Display properties oi AppSettings. The SplitContoiner contains 
a TabbableTextBox (with bindings to the FontSize and TobSpoces properties of AppSettings) and a 
RulerContainer (with bindings to ShowRuler and ShowGridLines). All these bindings strongly suggest 
that the DataContext of Mo in Page is set to an instance of AppSettings. 

The bottom of the XAML file has the Button definitions for the application bar. 

As you might expect, the code-behind file is the longest file in the project, but「m going to discuss 
it in various modular sections so that it won’t be too overwhelming. Here are the constructor, Loaded 
handler, and a few simple methods: 


Project: XamICruncher I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 
{ 

AppSettings appSettings; 

StorageFile 1oadedStorageFi1e; 

public MainPageO 
{ 

this. InitializeComponent(); 
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// Why aren't these set in the generated C# files? 
editBox = splitContainer.Chi 1dl as TabbableTextBox; 
resultContainer = splitContainer.Chi 1d2 as RulerContainer ; 


// Set a fixed-pitch font for the TextBox 
Language language = 

new Language (Windows.Globalization. Language. CurrentlnputLanguageTag); 

LanguageFontGroup 1anguageFontGroup = new LanguageFontGroup(l anguage.LanguageTag); 
LanguageFont 1anguageFont = 1anguageFontGroup.FixedWidthTextFont; 
editBox.FontFamily = new FontFami1y (1anguageFont.FontFami1y); 

Loaded += OnLoaded; 

Application .Current.Suspending += OnAppl i cationSuspending; 

} 

async void OnLoaded(object sender, RoutedEventArgs args) 

{ 

// Load AppSettings and set to DataContext 
appSettings = new AppSettings (); 
this .DataContext = appSettings; 

// Load any file that may have been saved 

StorageFolder local Folder = ApplicationData. Current.LocalFolder; 

StorageFi1e storageFi1e = await 1ocalFolder.CreateFi1 eAsync("Xaml Cruncher.xaml" , 

CreationCol1isionOption .OpenlfExists); 
editBox.Text = await FilelO. ReadTextAsync(storageFile); 

if (editBox.Text.Length == 0) 
await SetDefaultXamlFile(); 

// Other initialization 
ParseText(); 

editBox. Focus(FocusState .Programmatic); 

DisplayLineAndColumn(); 

} 

async void OnApplicationSuspending (object sender, SuspendingEventArgs args) 

{ 

// Save application settings 
appSettings.Save(); 

// Save text content 

SuspendingDeferral deferral = args.SuspendingOperation.GetDeferral(); 

await PathIO .Wri teTextAsync("ms-appdata : ///local/XamlCruncher.xaml" , editBox.Text); 

deferral.Complete(); 


async Task SetDefaultXamlFi1e() 

{ 

editBox.Text = 

"<Page xmlns=\"http://schemas.microsoft.com/winfx/2006/xaml/presentation\"\r\n" + 
" xml ns : x=\"http://schemas.microsoft.com/winfx/2006/xaml\">\r\n\r\n" + 

" <TextBlock Text=\"Hel1o, Windows 8!\"\r\n" + 

" FontSize=\"48\" />\r\n\r\n" + 

"</Page>"; 
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editBox.IsModified = false; 
1oadedStorageFi1e = null; 
fi1enameText.Text = "" : 


void OnEditBoxSelectionChanged (obj ect sender, RoutedEventArgs args) 

{ 

DisplayLineAndColumn(); 

} 

void DisplayLineAndColumn() 

{ 

int line, col; 

editBox.GetPositionFromIndex(editBox.SelectionStart, out line, out col); 

1ineColText.Text = String.Format("Line {0} Col {1}", line + 1, col + 1); 

if (editBox.SelectionLength >0) 

{ 

edi tBox.GetPositionFromIndex(editBox.Selecti onStart + editBox.SelectionLength - 1, 

out line, out col); 

1ineColText.Text += String. Format(" - Line {0} Col {1}" , line + 1, col + 1); 

} 

} 


} 

The constructor begins by fixing a little bug involving the edi tBox and resultContainer fields. 
The XAML parser definitely creates these fields during compilation, but they are not set by the 
InitiolizeComponent call at run time. 


The remainder of the constructor sets a fixed-pitch font in the TabbableTextBox based on the 
predefined fonts available from the LanguageFontGroup class. This is apparently the only way to get 
actual font family names from the Windows Runtime. (In Chapter 15, "Going Native," I demonstrate 
how to use DirectWrite to obtain the collection of fonts installed on the system.) 

The remaining initialization occurs in the Loaded event handler. The Data Context of the page is set 
to the AppSettings instance, as you probably anticipated from the data bindings in the MainPage.xaml 
file. 

The OnLooded method continues by loading a previously saved file or (if it doesn’t exist) setting 
a default piece of XAML in the TabbableTextBox and calling PorseText to parse it. (You'll see how this 
works soon.) The TabbableTextBox \s assigned keyboard input focus, and OnLooded concludes by dis¬ 
playing the initial line and column, which is then updated whenever the TextBox selection changes. 

You might wonder why SetDefaultXamIFile is defined as a sync and returns Task when it does not 
actually contain any asynchronous code. You’ll see later that this method is used as an argument to 
another method in the file I/O logic, and that’s the sole reason I had to define it oddly. The compiler 
generates a warning message because it doesn’t contain any await logic. 


CHAPTER 8 App Bars and Popups 


315 


Parsing the XAML 


The major job of XamICruncher is to pass a piece of XAML to Xa ml Reader. Load and get out an object. 
A property of the AppSettings class named AutoPorsing allows this to happen with every keystroke, or 
the program waits until you press the Refresh button on the application bar. 

If XamIReader.Lood encounters an error, it raises an exception, and the program then displays that 
error in red in the status bar at the bottom of the page and also colors the text in the TabbableTextBox 
red. 

Project: XamICruncher I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

Brush textBlockBrush, textBoxBrush, errorBrush; 

public MainPage() 

{ 

// Set brushes 

textBlockBrush = Resources ["Appl icationForegroundThemeBrush"] as SolidColorBrush; 
textBoxBrush = Resources ["Text BoxForegroundThemeB rush"] as SolidColorBrush; 
errorBrush = new SolidColorBrush (Colors. Red); 

} 


void OnRefreshAppBarButtonCli ck(object sender, RoutedEventArgs args) 

{ 

ParseText(); 

this .BottomAppBar.IsOpen = false; 

} 

void OnEditBoxTextChanged(object sender, RoutedEventArgs e) 

{ 

if (appSettings.AutoParsing) 

ParseTextO ; 

} 

void ParseTextO 

{ 

object result = null; 
try 

result = XamlReader. Load(editBox.Text); 

} 

catch (Exception exc) 

{ 

SetErrorText(exc.Message); 
return ; 

} 

if (result == null) 
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{ 


SetErrorText("Nul 1 result") ; 


} 

else if (!(result is UIE1 ement)) 

{ 

SetErrorText( "Result is " + result.GetTypeC).Name); 

} 

else 

{ 

resultContainer.Chi 1d = result as UIE1ement ; 

SetOkText(); 
return ; 

} 

} 

void SetErrorText(stri ng text) 

{ 

SetStatusText(text ， errorBrush, errorBrush); 

} 

void SetOkTextO 

{ 

SetStatusText("OK", textBlockBrush, textBoxBrush); 

} 

void SetStatusText(stri ng text, Brush statusBrush, Brush editBrush) 
{ 

statusText.Text = text; 

statusText.Foreground = statusBrush; 

editBox.Foreground = editBrush; 



It could be that a chunk of XAML successfully passes XamlReader.Load with no errors but then 
raises an exception later on. This can happen particularly when XAML animations are involved 
because the animation doesn’t start up until the visual tree is loaded. 

The only real solution is to install a handler for the UnhandledException event defined by the 
Application object, and that’s done in the conclusion of the Loaded handler: 

Project: XamICruncher I File: MainPage.xaml.es (excerpt) 

async void OnLoaded(object sender, RoutedEventArgs args) 


Application .Current.UnhandledException += (excSender, excArgs)=> 

{ 

SetErrorText(excArgs.Message); 
excArgs.Handled = true ; 

}； 

} 

The problem with something like this is that you want to make sure that the program isn’t going to 
have some other kind of unhandled exception that isn’t a result of some errant code. 
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Also, when Visual Studio is running a program in its debugger, it wants to snag the unhandled 
exceptions so that it can report them to you. Use the Exceptions dialog from the Debug menu to indi¬ 
cate which exceptions you want Visual Studio to intercept and which should be left to the program. 


XAML Files In and Out 


Whenever I approach the code involved in loading and saving documents, I always think it’s going to 
be easier than it turns out to be. Here’s the basic problem: Whenever a New or Open command oc¬ 
curs, you need to check if the current document has been modified without being saved. If that's the 
case, a message box should be displayed asking whether the user wants to save the file. The options 
are Save, Don’t Save, and Cancel. 

The easy answer is Cancel. The program doesn’t need to do anything further. If the user selects 
the Don’t Save option, the current document can be abandoned and the New or Open command 
can proceed. 

If the user answers Save, the existing document needs to be saved under its file name. But that file 
name might not exist if the document wasn’t loaded from a disk file or previously saved. At that point, 
the Save As dialog box needs to be displayed. But the user can select Cancel from that dialog box as 
well, and the New or Open operation ends. Otherwise, the existing file is first saved. 

Let’s first look at the methods involved in saving documents. The application button has Save and 
Save As buttons, but the Save button needs to invoke the Save As dialog box if it doesn’t have a file 
name for the document: 

Project: XamICruncher | File: MainPage.xaml.es (excerpt) 

async void OnSaveAsAppBarButtonCli ck(object sender, RoutedEventArgs args) 

{ 

StorageFile storageFi1e = await GetFileFromSavePicker(); 

if (storageFi1e == null) 
return ; 

await SaveXamlToFile(storageFile); 

} 

async void OnSaveAppBarButtonCli ck(object sender, RoutedEventArgs args) 

{ 

Button button = sender as Button ; 
button.IsEnabled = false; 

if (1oadedStorageFi1e != null) 

{ 

await SaveXamlToFi1e(loadedStorageFi1e); 

} 

else 

{ 

StorageFi1e storageFi1e = await GetFi1eFromSavePicker(); 
if (storageFi1e != null) 


318 PART Elementals 



{ 


await SaveXamlToFi1e(storageFi1e); 


} 

} 

button.IsEnabled = true; 

} 

async Task<StorageFi1 e> GetFi1eFromSavePicker() 

{ 

Fi1eSavePicker picker = new Fi1eSavePi cker() ; 

picker.DefaultFi1eExtension = ".xaml" ; 

pi eke r.Fi1eTypeChoices.Add ("XAML" , new List<string> { ".xaml" }); 
picker.SuggestedSaveFi1e = loadedStorageFi1e; 
return await picker.PickSaveFileAsync(); 

} 

async Task SaveXamlToFi1 e(StorageFi le storageFi1e) 

{ 

loadedStorageFile = storageFile; 
string exception = null; 

try 

await Fi1elO .WriteTextAsync(storageFi1e, editBox.Text); 

} 

catch (Exception exc) 

{ 

exception = exc.Message; 

} 

if (exception != null) 

{ 

string message = String .Format("Coul d not save file {0} : {1}" , 

storageFi1e.Name, exception); 

MessageDialog msgdlg = new MessageDialog (message, "XAML Cruncher") ; 
await msgdlg.ShowAsyncC); 

} 

else 

{ 

editBox.IsModified = false; 

fi1enameText.Text = storageFi1e.Path; 

} 

} 


For the Save button, the handler disables the button and then enables it when it’s completed. 

I’m worried that the button might be re-pressed during the time the file is being saved and there 
might even be a reentrancy problem if the handler tries to save it again when the first save hasn’t 
completed. 

In the final method, the File 10.WriteTextAsync call is in a try block. If an exception occurs while 
saving the file, the program wants to use MessageDialog to inform the user. But asynchronous meth¬ 
ods such as ShowAsync can’t be called in a catch block, so the exception is simply saved for checking 
afterward. 
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For both Add and Open, XamICruncher needs to check if the file has been modified. If so, a 
message box must be displayed to inform the user and request further direction. This occurs in a 
method I’ve called ChecklfOkToTroshFile. Because this method is applicable for both the Add and 
Open buttons, I gave this method an argument named commandAction of type Func<Task>, a 
delegate meaning a method with no arguments that returns a Task. The Click handler for the Open 
button passes the LoadFileFrom Open Picker method as this argument, and the handler for the Add 
button uses the aforementioned SetDefoultXomIFile. 


Project: XamICruncher I File: MainPage.xaml.es (excerpt) 

async void OnAddAppBarButtonCli ck(object sender, RoutedEventArgs args) 

{ 

Button button = sender as Button ; 
button.IsEnabled = false; 

await ChecklfOkToTrashFi1e(SetDefaultXamlFi1e); 

button.IsEnabled = true ; 

this .BottomAppBar.IsOpen = false; 

} 

async void OnOpenAppBarButtonCli ck(object sender, RoutedEventArgs args) 

{ 

Button button = sender as Button ; 
button.IsEnabled = false; 

await ChecklfOkToTrashFi1e(LoadFi1eFromOpenPicker); 

button.IsEnabled = true; 

this .BottomAppBar.IsOpen = false; 

} 

async Task ChecklfOkToT rashFi1 e(Func<Task> commandAction) 

{ 

if (!editBox.IsModified) 

{ 

await commandAction(); 
return ; 

} 

string message = 

String. Format ("Do you want to save changes to {0}?" , 

1oadedStorageFi1e == null ? "(untitled)" : 1oadedStorageFi1e.Name); 

MessageDialog msgdlg = new MessageDialog (message, "XAML Cruncher") ; 
msgdlg.Commands.Add (new UICommand("Save" , null, "save ")) ； 
msgdlg.Commands.Add (new UICommand("Don 't Save" , null, "dont ")) ； 
msgdlg.Commands.Add (new UICommand("Cancel " , null, "cancel")); 
msgdlg.DefaultCommandlndex = 0; 
msgdlg.CancelCommandlndex = 2; 

IUICommand command = await msgdlg.ShowAsyncO; 

if ((stri ng)command.Id == "cancel ") 
return ; 
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if ((stri ng)command.Id == "dont") 

{ 

await commandAction(); 
return ; 

} 

if (1oadedStorageFi1e == null) 

{ 

StorageFi1e storageFi1e = await GetFi1eFromSavePicker(); 

if (storageFi1e == null) 
return ; 

1oadedStorageFi1e = storageFi1e; 

} 

await SaveXamlToFi1e(1oadedStorageFi1e); 
await commandActionO; 


async Task LoadFi1eFromOpenPicker() 

{ 

FileOpenPicker picker = new Fi1eOpenPi cker(); 

picker.FileTypeFiIter.Add (". xaml ") ; 

StorageFile storageFi 1 e = await picker.PickSingleFileAsyncC); 


if (storageFi1e != null) 

{ 

string exception = null; 


} 



editBox.Text = await Fi1elO. ReadTextAsync(storageFi1e); 

} 

catch (Exception exc) 

{ 

exception = exc.Message; 


} 


if (exception != null) 

{ 

string message = String. Format("Coul d not load file {0} : {1}" , 

storageFi1e.Name, exception); 

MessageDialog msgdlg = new MessageDialog (message, "XAML Cruncher") ; 
await msgdlg.ShowAsync(); 

} 

else 


{ 

editBox.IsModified = false; 

1oadedStorageFi1e = storageFile; 
filenameText.Text = 1oadedStorageFi1e.Path; 

} 
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The Settings Dialog 


When the user clicks the Settings button, the handler instantiates a User Control derivative named 
SettingsDiolog and makes it the child of a Popup. Among these options is the orientation of the dis¬ 
play. You'll recall I defined an EditOrientotion enumeration for the four possibilities. Accordingly, the 
project also contains an EditOrientotionRodioButton for storing one of the four values as a custom tag: 

Project: XamICruncher | File: EditOrientationRadioButton.es 
using Windows.UI.Xaml .Controls; 


namespace XamICruncher 

{ 

public cl ass EditOrientationRadioButton : RadioButton 

{ 

public EditOrientation EditOrientationTag { set; get ; 

} 


} 



The SettingsDialog.xaml file arranges all the controls in a StackPonel: 


Project: XamICruncher I File: SettingsDialog.xaml (excerpt) 
<UserControl … > 


<UserControl.Resources 〉 

<Style x : Key="Di alogCaptionTextStyle" 

TargetType="Text Block" 

BasedOn="{Stati cResource CaptionTextStyl e}"> 
〈Setter Property="FontSi ze" Value="14.67" /> 
〈Setter Property="FontWei ght" Val ue="Semi Light” /> 
〈Setter Property="Margi n" Value="7 0 0 0" /> 
</Style> 

</UserControl.Resources 〉 


〈Border Background="{Stati cResource ApplicationPageBackgroundThemeBrush} 
BorderBrush="{Stati cResource ApplicationForegroundThemeBrush}" 
BorderThi ckness="l"> 

<StackPanel Margi n="24"> 

<TextBlock Text="Xaml Cruncher settings” 

Styl e="{StaticResource SubheaderTextStyl e}" 

Margin，。 0 0 12" /> 

<!-- Auto parsing --> 

<ToggleSwitch Header="Automati c parsing" 

IsOn="{Binding AutoParsing ， Mode=TwoWay}" /> 

<!-- Orientation --> 

<TextBlock Text="Ori entation" 

Styl e="{StaticResource DialogCaptionTextStyl e}" /> 

<Grid Name="ori entationRadioButtonGrid" 

Margi n="7 0 0 0"> 

<Crid.RowDefinitions> 

<RowDefinition Height="Auto" /> 

〈RowDefinition Height="Auto" /> 
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</Grid.RowDefinitions> 

<Grid.ColumnDefinitions> 

<ColumnDefinition Wi dth="Auto" /> 
<ColumnDefinition Wi dth="Auto" /> 
</Grid.ColumnDefinitions> 


<Grid.Resources 〉 

〈Style TargetType="Border"> 

<Setter Property=" BorderBrush" 

Val ue="{StaticResource ApplicationForegroundThemeBrush}" /> 
〈Setter Property="BorderThi ckness" Value="l" /> 

〈Setter Property="Paddi ng" Value="3" /> 

</Style> 


<Style TargetType="TextBlock"> 

〈Setter Property="TextAl ignment" Val ue="Center" /> 
</Style> 


<Style TargetType=" local : EditOrientationRadioButton"> 
〈Setter Property="Margi n" Value="0 6 12 6" /> 

</Style> 

</Grid.Resources 〉 

<1ocal : EditOrientationRadioButton Grid. Row="0" Grid.Col umn="0" 

EditOrientati onTag="Left" 
Checked="OnOri entationRadioButtonChecked"> 
<StackPanel Orientati on="Hori zontal"> 

<Border> 

<TextBlock Text="edi t" /> 

</Border> 

<Border> 

〈TextBlock Text="di splay" /> 

</Border> 

</StackPanel> 

</local : EditOrientationRadioButton> 

<1ocal : EditOrientationRadioButton Grid. Row="0" Grid.Column="l" 

EditOrientati onTag="Bottom" 
Checked="OnOri entationRadioButtonChecked"> 
<StackPanel > 

<Border> 

<TextBlock Text="di splay" /> 

</Border> 

<Border> 

〈TextBlock Text="edi t" /> 

</Border> 

</StackPanel> 

</local : EditOrientationRadioButton> 

<1ocal : EditOrientationRadioButton Grid. Row="l" Grid.Col umn="0" 

EditOrientati onTag="Top" 
Checked="OnOri entationRadioButtonChecked"> 
<StackPanel > 

<Border> 

<TextBlock Text="edit" /> 

</Border> 
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<Border> 

<TextBlock Text="di splay" /> 

</Border> 

</StackPanel> 

</local : EditOrientationRadioButton> 

<1ocal : EditOrientationRadioButton Grid.Row="l" Grid.Column="l 

EditOrientationTag="Ri ght" 
Checked="OnOri entationRadioButtonChecked"> 
<StackPanel Orientati on="Hori zontal"> 

<Border> 

<TextBlock Text="di splay" /> 

</Border> 

<Border> 

<TextBlock Text="edit" /> 

</Border> 

</StackPanel> 

</local : EditOrientationRadioButton> 

</Gri d> 


<!-- Ruler --> 

<ToggleSwitch Header="Rul er" 

OnConten t=" Show" 

OffContent="Hi de" 

IsOn="{Binding ShowRuler, Mode=TwoWay}" /> 


<!-- Grid lines --> 

<ToggleSwitch Header="Gri d lines" 

OnConten t=" Show" 

OffContent="Hi de" 

IsOn="{Bi nding ShowGridLines , Mode=TwoWay}" /> 

<!-- Font size --> 

<TextBlock Text="Font size" 

Styl e="{StaticResource DialogCaptionTextStyle}" /> 

〈Slider Val ue="{Binding FontSize , Mode=TwoWay}" 

Minimum="10" 

Maximum="48" 

Margin="7 0 0 0" /> 

<!-- Tab spaces --> 

<TextBlock Text="Tab spaces" 

Styl e="{StaticResource DialogCaptionTextStyle}" /> 

〈Slider Val ue="{Bi nding TabSpaces , Mode=TwoWay}" 

Minimum= ,, l" 

Maximum= ,, 12" 

Margin="7 0 0 0" /> 

</StackPanel> 

</Border> 

</UserControl > 
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All the two-way bindings strongly suggest that the Data Context is set to an instance of AppSettings, 
just like MainPoge. It’s actually the some instance of AppSettings, which means that any changes in 
this dialog are automatically applied to the program. 

This means that you can’t make a bunch of changes in the dialog and hit Cancel. There is no 
Cancel button. To compensate, it might make sense for a dialog to have a Defaults button that re¬ 
stores everything to its factory-new condition. 

A significant chunk of the XAML file is devoted to the four EditOrientotionRadioButton controls. 
The content of each of these is a StackPanel with two bordered TextBlock elements, to create a little 
graphic that resembles the four layout options you saw in the earlier screen shot (that is, the third 
screen shot in the "Introducing XamlCruncher” section). 

The dialog contains three instances of ToggleSwitch. By default, the On Content and Off Con tent 
properties are set to the text string "On” and "Off,” but I thought "Show” and "Hide" were better for 
the ruler and grid displays. 

ToggleSwitch also has a Header property that displays text above the switch. In the screen shot 
I just referred to, the labels "Automatic parsing,” "Ruler," and "Grid lines” are all displayed by the 
ToggleSwitch. I thought the labels looked good, so I made an effort to duplicate the font and place¬ 
ment with the Style labeled as "DialogCaptionTextStyle.” 

A Slider is used to set the font size, which might seem reasonable, but I also use a Slider to set the 
number of tab spaces, which I’ll admit doesn’t seem reasonable at all. Even though the AppSettings 
class defines the TobSpoces property as an integer, the binding with the Value property of the Slider 
works regardless, and the Slider proves to be a convenient way to change the property. 

The only chore left for the code-behind file is to manage the RodioButton controls: 

Project: XamICruncher | File: SettingsDialog.xaml.es 

using Windows.UI.Xaml; 

using Windows.UI.Xaml.Controls; 

namespace XamICruncher 
{ 

public sealed partial cl ass SettingsDialog : UserControl 
{ 

public SettingsDialogO 
{ 

this. InitializeComponent(); 

Loaded += OnLoaded; 

} 

// Initialize RadioButton for edit orientation 
void OnLoaded (object sender, RoutedEventArgs args) 

{ 

AppSettings appSettings = DataContext as AppSettings; 
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if (appSettings != null) 


foreach (UIE1ement child in orientationRadioButtonGrid.Chi 1dren) 

{ 

EditOrientationRadioButton radioButton = 
child as EditOrientationRadioButton ; 

radioButton.IsChecked = 

appSettings.EditOrientation == radioButton.EditOrientationTag; 



// Set EditOrientation based on checked RadioButton 

void OnOrientationRadioButtonChecked (object sender, RoutedEventArgs args) 

{ 

AppSettings appSettings = DataContext as AppSettings ; 

EditOrientationRadioButton radioButton = sender as EditOrientationRadioButton; 


} 


if (appSettings != null) 

appSettings.EditOrientation = radioButton.EditOrientationTag; 


The display of the dialog is very similar to the AppBarPad program: 


Project: XamICruncher I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 


void OnSettingsAppBarButtonCli ck(object sender, RoutedEventArgs args) 

{ 

Setti ngsDialog settingsDialog = new SettingsDialogO ; 

settingsDialog.DataContext = appSettings; 

Popup popup = new Popup 

{ 

Child = settingsDialog, 

IsLightDismissEnabled = true 

}； 


settingsDialog.Loaded += (dialogSender, dialogArgs)=> 


}； 


popup.Vertical Offset = this. Actual Height - 
popup.HorizontalOffset = 24; 


settingsDialog.Actual Height 
this. BottomAppBar.ActualHeight - 
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24; 


popup.Closed += (popupSender, popupArgs)=> 


}； 


this. BottomAppBar.IsOpen = false; 


popup.IsOpen = true; 


} 

The Closed event handler for the Popup closes the application bar. The new settings are saved in the 
handler for the Suspending event that you’ve already seen. 


Beyond the Windows Runtime 

Earlier I mentioned some limitations to the XAML that you can enter in XamICruncher. Elements 
cannot have their events set because events require event handlers and event handlers must be 
implemented in code. Nor can the XAML contain references to external classes or assemblies. 

However, the parsed XAML runs in the XamICruncher process, which means that it does have 
access to any classes that XamICruncher has access to, including the custom classes I created for the 
program. Here’s a piece of XAML that includes a namespace declaration for local. This enables it to 
use the SplitContainer and nests two instances of it: 



xmlns= 


http://schemas 


microsoft 


com/winfx/2006/xaml/presentation 


〈Page 


//schemas 


rosoft.com/winfx/2006/xaml 


xmlns 


http 


I 1C 


xmlns 


local= 


XamICruncher 


using 


〈local 


SplitContainer 


Vertical > 


Orientation: 


〈local 


SplitContainer.Childl> 


〈local 


SplitContainer 〉 


〈 local:SplitContainer 


Childi> 


http://www.charlespetzold.com/pw 6 /Petzol( 


〈Image 


Source 


Stretch: 


Fill 


〈 /local:SplitContainer.Childl> 


〈local 


SplitContainer.Child 2 > 


〈TextBlock 


FontSize= 24 " 


Wrap 


Textwrapping 


early 


long 


time 


used 


bed 


to 


to 


Sometime 


go 


candle 


would 


close 


quickly 


that 


nac 


my 


,my 
going 


eyes 




sleep. 


And 


half 


hour 


later 


th» 


to 


say 


an 


sleep 


would 


awaken 


would 


to 


to 


try 


to 


go 


me; 


which. 


imagined. 


still 


m 
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</TextBlock> 


</local:SplitContainer.Child 2 > 


〈 /local:SplitContainer> 


〈 /local:SplitContainer.Childl> 


〈local 


SplitContainer 


Child 2 > 


〈Ellipse 


Fill="Blue u 


/> 


</local:SplitContainer.Child 2 > 


〈/local 


SplitContainer 〉 


</Page> 


This piece of XAML is among the downloadable code for this chapter, as is the XAML used for the 
earlier screen shots. 

This is interesting because it means that XamICruncher really can go beyond the Windows Runtime 
and let you experiment with custom classes. 
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CHAPTER 9 

Animation 


T he topic of animation might at first seem as if it doesn’t quite belong in the "Elementals" section 
of this book. Perhaps the subject is more suited for advanced programmers working on games 
or physics simulations. Animation just doesn’t seem appropriate in sedate and dignified business 
applications (except perhaps on casual Fridays). 

But animation has more of a central role in Windows 8 applications than you might think. You’ll 
discover part of that role in Chapter 11, "The Three Templates,” which shows how to use XAML to 
create ControlTemplate objects that entirely redefine the appearances of controls. Although the most 
important part of a ControlTemplate is a visual tree, the template must also indicate how the appear¬ 
ance of the control changes under certain conditions. For example, a Button might be highlighted 
when it’s pressed and "grayed out” when it’s disabled. All these changes in appearance within the 
ControlTemplate are defined as animations — even if the change is instantaneous and doesn’t really 
seem much like an animation. 

Animations also come into play to define transitions between different application views or the 
movement of items during changes to a collection. Try moving a tile on the Start screen from one 
location to another and you’ll see neighboring tiles shift in response. These are animations, and this is 
an important part of the fluid nature of Windows 8 aesthetics. 


The Windows.Ul.Xaml.Media.Animation Namespace 

In Chapter 3, "Basic Event Handling," I demonstrated how to animate objects by using the 
CompositionTarget.Rendering event, a technique I referred to as a "manual” animation. Although a 
manual animation can be powerful, it has some limitations. The callback method always runs in the 
user interface thread, which means that the animation can interfere with program responsiveness to 
user input. 

Also, the animations I demonstrated with CompositionTarget.Rendering were all linear — that 
is, they increased or decreased a value linearly over a period of time. Animations are often more 
pleasant when they have a little variation, usually by speeding up at the beginning and slowing down 
toward the end, perhaps with a little "bounce” for extra realism. You can certainly perform animations 
of this sort using CompositionTarget.Rendering, but the mathematics can be challenging. 
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In contrast in this chapter I’ll be demonstrating instead the built-in Windows Runtime animation 
facility that consists of 71 classes, 4 enumerations, and 2 structures in the Windows.Ul.Xoml.Medio 
•Animation namespace. These animations often run on background threads and support several 
features for sophisticated effects. Very often, you can define animations entirely in XAML and then 
trigger them from code or (in one particular but common case) directly from XAML. 


Of course, the very idea of mastering an animation facility with 71 classes can be intimidating. 
Fortunately, these classes fall into just a few general categories, and by the end of this chapter, the 
namespace should be entirely comprehensible. 

Animation involves change, and what these animations change is a property of an object. This 
property is often referred to as the "target” of the animation. The Windows Runtime animations 
require this target property to be backed by a dependency property and therefore defined in a class 
that derives from DependencyObject. 

Some graphical environments have animations that are frame-based, meaning that the pacing of 
the animation is based on the frame rate of the video display. Different video frame rates on different 
hardware platforms might result in animations of different speeds. The Windows Runtime animations 
are instead time-based, meaning that they are based on actual durations of clock time: seconds and 
milliseconds. 

What happens if the thread running an animation needs to do some work and the animation 
misses a few ticks? A frame-based animation generally continues where it left off. A Windows Runtime 
time-based animation adjusts itself based on clock time and catches up to where it should be. 

Animation Basics 


Let’s begin with the animation of the Fontsize property of a TextBlock, much like the ExpandingText 
program in Chapter 3. The SimpleAnimation project has a two-row Grid with a TextBlock and a 
Button to start the animation going. Very often, animations are defined in the Resources section of 
the root element of the XAML file. A simple animation like this one consists of a Storyboard and a 
DoubleAnimation: 


Project: SimpleAnimation I File: MainPage.xaml (excerpt) 
<Page … > 


<Page.Resources 〉 

<Storyboard x : Key="storyboard"> 

<DoubleAnimation Storyboard .TargetName="txtbl k" 

Storyboard.TargetPrope rty="FontSi ze" 
EnableDependentAnimati on="T rue" 
From="l" To="144" Duration="0:0: 3" /> 

</Storyboard> 

</Page.Resources 〉 


<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Grid.RowDefinitions> 

〈RowDefinition Height:"*" /> 
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<RowDefinition Height="*" /> 

</Grid.RowDefiniti ons> 

<TextBlock Name="txtbl k" 

Text="Ani mated Text" 

Grid.Row= ,, 0" 

FontSize="48" 

HorizontalAl ignment="Center" 

VerticalAli gnment="Center" /> 

<Button Content="Trigger! " 

Grid.Row= M l" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Center" 

Cli ck="OnButtonCl ick" /> 

</Grid> 

</Page> 

The name of the DoubleAnimation class doesn't mean that it performs two animations! This is an 
animation that targets properties of type Double. As you’ll see, the Windows Runtime also supports 
animations that target properties of type Point, Color, and Object. (An animation that targets proper¬ 
ties of type Object might seem as if it’s the only animation you’d need, but in reality it’s limited to 
setting discrete property values rather than smoothly animating them.) 


The Windows Runtime requires that an animation object such as DoubleAnimation be a child of a 
Storyboard. A Storyboard can have multiple children performing parallel animations, and the job of 
the Storyboard is to provide a framework for synchronizing the children. 


Storyboard also defines two attached properties named TorgetName and TargetProperty. You set 
these properties in the animation object to indicate the name of the object you’re targeting, and the 
property of that object you wish to animate: 

<Storyboard x : Key="storyboard"> 

<DoubleAnimation Storyboard .TargetName="txtbl k" 

Storyboard.TargetPrope rty="FontSi ze" 

... /> 

</Storyboard> 


By default, animations are performed in a secondary thread so that the user interface thread 
remains free to respond to user input. However, an animation that targets the FontSize property of 
a TextBlock must run in the user interface thread because a change in the font size triggers a layout 
change. The Windows Runtime is reluctant to run animations in the user-interface thread, even to the 
extent of implementing a default behavior to disallow them! To let the Windows Runtime know your 
intention — yes, you want the animation to run even if it happens in the user interface thread — you 
must set the EnableDependentAnimation property to true: 

<Storyboard x:Key="storyboard"> 

<DoubleAnimation Storyboard .TargetName="txtbl k" 

Storyboard.TargetPrope rty="FontSi ze" 

EnableDependentAnimati on="T rue" 


</Storyboard> 
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In this context, the word "dependent” means "dependent on the user interface thread." 

The remainder of this particular animation indicates that we want to animate the value of the 
Font Size property from 1 to 144 over the course of three seconds: 

<Storyboard x: Key="storyboard"> 

<DoubleAnimation Storyboard .TargetName="txtbl k" 

Storyboard.TargetPrope rty="FontSi ze" 

EnableDependentAnimati on="T rue" 

From="l" To= ,, 144_ , Durati on="0 :0: 3" /> 

</Storyboard> 

The duration of the animation is specified in hours, minutes, and seconds. All three values and two 
colons are required. If you specify just one number, it will be interpreted as an integral number of 
hours; two numbers separated by a colon are interpreted as hours and minutes. The seconds can 
include fractional seconds. If you need an animation that runs more than a day, you can precede the 
hours with a number of days and a period. 

When you first run this program, the TextBlock is displayed with a 48-pixel height, as specified in 
the TextBlock element in the XAML file: 


Animated Text 


Trigger! 


The Storyboard doesn’t run by itself. It needs to be triggered, usually by something happening in the 
user interface. In this program, the Click handler for the Button obtains a reference to the Storyboard 
by accessing the Resources collection, and then it calls Begin: 


Project: SimpleAnimation | File: MainPage.xaml.es 

using Windows.UI.Xaml; 

using Windows.UI.Xaml.Controls; 

using Windows.UI.Xaml.Media.Animation; 


332 PART Elementals 




namespace SimpleAnimation 
{ 

public sealed partial class MainPage : Page 
{ 

public MainPage() 

{ 

this. InitializeComponent(); 

} 

void OnButtonCli ck(object sender, RoutedEventArgs args) 

{ 

(thi s .Resources ["storyboard"] as Storyboard) .Begin(); 

} 



Notice the using directive for Windows.Ul.Xoml.Media.Animation. This is not provided for you 
automatically by the Visual Studio template. 


When the storyboard is started, the Text Block immediately jumps to a Font Size of 1 (the From value 
in DoubleAnimation), and then the Fontsize increases to 144 over the course of three seconds. The in¬ 
crease is linear: At the one-second mark, the FontSize is 48-2/3 pixels, and at two seconds, it’s 96-1/3. 
At the end of three seconds, the animation stops and the TextBlock remains at the 144-pixel size: 


Animated Text 

Trigger! 


You can click the button again, and the animation starts over again. In fact, you can click the 
button repeatedly while the animation is running, and each time it starts over again at the 1-pixel size. 
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Animation Variation Appreciation 


When the animation in the SimpleAnimation program completes, the Fontsize remains at the value 
specified by the To property of DoubleAnimation. This is a result of the value of the Fill Behavior prop¬ 
erty of DoubleAnimation, which by default is the enumeration member HoldEnd. You can alternatively 
set it to Stop: 

<Storyboard x: Key="storyboard"> 

<DoubleAnimation Storyboard .TargetName="txtb1 k" 

Storyboard.TargetPrope rty="FontSi ze" 

EnableDependentAnimati on="T rue" 

Fill Behavior="Stop" 

From= ,, l" 10="144" Durati on="0 :0: 3" /> 

</Storyboard> 

Now at the end of the animation, the animation is released from the target property and Font Size 
reverts to its pre-animation value of 48. 

Another variation is to leave out the From or To value. For example, 

<Storyboard x : Key="storyboard"> 

<DoubleAnimation Storyboard .TargetName="txtbl k" 

Storyboard.TargetPrope rty="FontSi ze" 

EnableDependentAnimati on="T rue" 

From="l" Duration="0:0: 3" /> 

</Storyboard> 

Now the animation begins at 1 but goes up only to the pre-animation value of 48. The increase in size 
proceeds at a slower rate because the duration is still three seconds. 

This animation causes Font Size to go from its current value up to 144 over three seconds: 

<Storyboard x : Key="storyboard"> 

<DoubleAnimation Storyboard .TargetName="txtbl k" 

Storyboard.TargetPrope rty="FontSi ze" 

EnableDependentAnimati on="T rue" 

To= n 144 M Duration="0:0:3" /> 

</Storyboard> 

I say the Font Size goes from "its current value” because that value isn’t necessarily the pre-animation 
value of 48. Click the button, and while the Text Block is still increasing in size, click the button again. 
Each successive click effectively terminates the existing animation and starts a new animation from 
the current Fonts ize. Each new click slows down the rate of increase because the length of the 
animation is still three seconds. 

You might assume that the DoubleAnimation class defines the To and From properties as type 
double. That’s almost true. They are actually of type nullable double, and null is the default value. This 
is how DoubleAnimation can determine whether these properties are set. 
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The other option is By: 

<Storyboard x:Key="storyboard"> 

<DoubleAnimation Storyboard .TargetName="txtbl k" 

Storyboard.TargetPrope rty="FontSi ze" 

EnableDependentAnimati on="T rue" 

By="100" Duration="0:0:3" /> 

</Storyboard> 

Now each click of the button triggers an animation that increases the Fontsize by another 100 pixels 
over the course of three seconds. The text just gets larger and larger and larger. 


Try going back to the original settings and add an attribute that sets AutoReverse to true: 

<Storyboard x : Key="storyboard"> 

<DoubleAnimation Storyboard .TargetName="txtbl k" 

Storyboard.TargetPrope rty="FontSi ze" 

EnableDependentAnimati on="T rue" 

From="l" To= M 144" Duration="0:0: 3" 

AutoReverse="True" /> 

</Storyboard> 

When this animation is triggered, the FontSize jurr\ps down to 1, goes up to 144 over the course of 
three seconds, and then goes back down to 1 over another three seconds, at which time the anima¬ 
tion is completed. The entire animation is six seconds in length. Set Fill Behavior to Stop, and the 
Font Size will jump back to its pre-animation value of 48 at the end of those six seconds. 

You can also set a RepeotBehavior attribute with or without AutoReverse. The following 
combination indicates that you want to perform three entire cycles of increasing and decreasing 
the Font Size: 

<Storyboard x:Key="storyboard"> 

<DoubleAnimation Storyboard .TargetName="txtbl k" 

Storyboard.TargetPrope rty="FontSi ze" 

EnableDependentAnimati on="T rue" 

From= M l" To="144" Duration="0:0: 3" 

AutoReverse="True" 

RepeatBehavior="3x" /> 

</Storyboard> 


The entire animation lasts for 18 seconds. 

You can also set RepeotBehavior to a duration: 

<Storyboard x:Key="storyboard"> 

<DoubleAnimation Storyboard .TargetName="txtbl k" 

Storyboard.TargetPrope rty="FontSi ze" 
EnableDependentAnimati on="T rue" 
From="l" To="144" Duration="0:0: 3" 
AutoReverse="T rue" 
RepeatBehavior="0:0: 7.5" /> 

</Storyboard> 


CHAPTER 9 Animation 


335 


The total animation lasts 7.5 seconds. The Fontsize increases from 1 to 144 over the course of three 
seconds, decreases from 144 to 1 in another three seconds, and then starts to increase again but 
stops. The final Font Size value is 73.5. 

You can also set RepeatBehovior to Forever: 

<Storyboard x: Key="storyboard"> 

<DoubleAnimation Storyboard .TargetName="txtbl k" 

Storyboard.TargetPrope rty="FontSi ze" 

EnableDependentAnimation="T rue" 

From="l" To= n 144" Duration="0:0: 3" 

AutoReverse="True" 

RepeatBehavior="Forever" /> 

</Storyboard> 


And it does exactly that (or at least until you get bored and terminate the program). 
You can delay the start of an animation with the BeginTime property: 

<Storyboard x: Key="storyboard"> 

<DoubleAnimation Storyboard .TargetName="txtb1 k" 

Storyboard.TargetPrope rty="FontSi ze" 

EnableDependentAnimati on="T rue" 

BeginTime="0:0:l. 5" 

From="l" 10="144" Durati on="0 :0:3" /> 

</Storyboard> 


When you click the button, nothing will seem to happen for a second and a half, and then the 
TextBlock will jump to a 1-pixel size and start to expand. The animation concludes 4.5 seconds after 
the button click. 

Even with all these variations, all the animations so far have been linear. The Font Size always 
increases or decreases linearly by a certain number of pixels per second. One easy way to create 
a nonlinear animation is by setting the EasingFunction property defined by DoubleAnimotion. 

Break out the property as a property element, and specify one of the 11 classes that derive from 
Easing Function Base. Here's ElasticEose: 

<Storyboard x : Key="storyboard"> 

<DoubleAnimation Storyboard .TargetName="txtbl k" 

Storyboard.TargetPrope rty="FontSi ze" 

EnableDependentAnimati on="T rue" 

From= ,, l" To="144" Duration="0:0: 3"> 

<DoubleAnimation.EasingFunction> 

<ElasticEase /> 

</DoubleAnimation.EasingFuncti on> 

</DoubleAnimation> 

</Storyboard> 


You really need to try this out to see the effect. As the TextBlock gets larger, it actually goes beyond 
the 144-pixel size and then decreases to below 144 and back and forth a couple times, finally settling 
at the To value. (That behavior rather stretches the meaning of the word "ease"!) 
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EasingFunctionBose defines an EosingMode property that is inherited by all 11 derived classes. The 
default setting is the enumeration member Easing Mode.EoseOut, which means that the animation 
begins linearly and the special effect is applied at the end of the animation. You can specify Eoseln to 
apply the effect to the beginning of the animation or Ease In Out to the beginning and the end. 

Some Easing Function Base derivatives define their own properties for a little variation. ElasticEose 
defines an Oscillations property (an integer with a default value of 3 that indicates how many times 
the values swings back and forth) and a Springiness property, a double also with a default setting of 3. 
The lower the Springiness value, the more extreme the effect. Try this: 

<Storyboard x : Key="storyboard"> 

<DoubleAnimation Storyboard .TargetName="txtbl k" 

Storyboard.TargetPrope rty="FontSi ze" 

EnableDependentAnimati on="T rue" 

From= n l n To="144" Duration="0:0: 3"> 

<DoubleAnimation.EasingFunction> 

<E1asticEase Osci11ati ons="10" 

Springi ness="0" /> 

</DoubleAnimation.EasingFuncti on> 

</DoubleAnimati on> 

</Storyboard> 

A program to explore the easing functions is coming up soon. 

I mentioned earlier that an animation object such as DoubleAnimation must be a child of a 
Storyboard. Interestingly, Storyboard and DoubleAnimation are siblings in the class hierarchy: 


Object 

DependencyObject 

Timeline 

Storyboard 

DoubleAnimation 


Storyboard defines a Children property of type TimelineCollection, the attached properties 
TorgetNome and TargetProperty, as well as methods to pause and resume the animation. 
DoubleAnimation defines From, To, By, EnobleDependentAnimotion, and EasingFunction. 

All the other properties youVe seen so far — AutoReverse, BeginTime, Duration, Fill Behavior, 
and RepeatBehavior — are defined by Timeline, which means that you can set these properties on 
Storyboard to define behavior for all the children of the Storyboard. 

Timeline also defines a property named Speed Ratio: 

<Storyboard x : Key="storyboard"> 

<DoubleAnimation Storyboard .TargetName="txtbl k" 

Storyboard.TargetPrope rty="FontSi ze" 

EnableDependentAnimati on="T rue" 

SpeedRatio="10" 

From= ,, l" To="144" Duration="0:0: 3" /> 

</Storyboard> 
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This Speed Ratio setting causes the animation to go 10 times faster! Setting Speed Ratio on the 
DoubleAnimation is certainly allowed, but it’s much more common to set it on a Storyboard so that 
it applies to all the animation children within that Storyboard. You can use Speed Ratio for fine-tuning 
the speed of an animation without changing all the individual Duration times or for debugging 
complex collections of animations. For example, set the Speed Ratio to 0.1 to slow down the animation 
so that you can better see what it’s doing. 

Timeline also defines a Completed event, which you can set on either a Storyboard or a 
DoubleAnimation to be notified when an animation has completed. 

It’s also possible to define an animation entirely in code. The XAML file for the 
SimpleAnimationCode project has a Grid with nine Button elements sharing the same Click event 
handler. No Storyboard or DoubleAnimation appears in the XAML file: 


Project: SimpleAnimationCode I File: MainPage.xaml (excerpt) 

<Page … > 

<Page.Resources 〉 

<Style TargetType="Button"> 

〈Setter Property="Content" Value="Trigger! " /> 

〈Setter Property="FontSi ze" Value="48" /> 

〈Setter Property="Hori zontalA1ignment" Val ue="Center" /> 
〈Setter Property="Verti calA1ignment" Val ue="Center" /> 
〈Setter Property="Margi n" Value="12" /> 

</Style> 

</Page.Resources 〉 


<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Grid HorizontalA1i gnment="Center" 

VerticalA1i gnment="Center"> 

<Grid.RowDefinitions> 

<RowDefinition Height="Auto" /> 

〈RowDefinition Hei ght="Auto" /> 

〈RowDefinition Height="Auto" /> 

</Grid.RowDefinitions> 

<Grid.ColumnDefinitions> 

<ColumnDefinition Wi dth="Auto" /> 

<ColumnDefinition Width="Auto" /> 

<ColumnDefinition Wi dth="Auto" /> 

</Grid.ColumnDefinitions> 


〈Button 
〈Button 
〈Button 
〈Button 
〈Button 
〈Button 
〈Button 
〈Button 
〈Button 
</Grid> 
</Gri d> 


Grid.Row="0" 

Grid.Row="0" 

Grid.Row="0" 

Grid.Row="l" 

Gn'd.Row="l" 

Grid.Row="l" 

Grid.Row="2" 

Grid.Row="2" 

Grid.Row="2" 


Grid.Col umn="0" 
Grid.Col umn="l" 
Grid.Col umn="2" 
Grid.Col umn="0" 
Grid.Col umn="l" 
Grid.Col umn="2" 
Grid.Col umn="0" 
Grid.Col umn="l" 
Grid.Col umn="2" 


Cli ck="OnButtonClick" /> 
Cl ick="OnButtonClick" /> 
Cli ck="OnButtonClick" /> 
Cl ick="OnButtonCl'i ck" /> 
Cli ck="OnButtonClick" /> 
Cli ck="OnButtonClick" /> 
Cli ck="OnButtonClick" /> 
Click="OnButtonClick" /> 
Cl ick="OnButtonCl'i ck" /> 


</Page> 
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In the code-behind file, you can create the Storyboard and DoubleAnimotion once and reuse the 
objects whenever you need to trigger the animation, or you can create them anew as needed. The 
first approach only works when the animation target is always the same object. This program poten¬ 
tially needs nine independent animations for the nine buttons, so it’s easiest just creating them on 
demand. Everything is in the Click handler: 

Project: SimpleAnimationCode | File: MainPage.xaml.es (excerpt) 

void OnButtonCli ck(object sender, RoutedEventArgs args) 

{ 

DoubleAnimation anima = new DoubleAnimation 
{ 

EnableDependentAnimation = true , 

To = 96, 

Duration = new Du rati on (new TimeSpan(0, 0, 1 ))， 

AutoReverse = true , 

RepeatBehavior = new RepeatBehavior(3) 

}； 

Storyboard .SetTarget(anima, sender as Button) ; 

Storyboard. SetTargetProperty(anima, "FontSize") ; 

Storyboard storyboard = new StoryboardO; 

storyboard .Chi "Id ren .Add (ani ma); 
storyboard.Begin(); 

} 

In the earlier XAML definition of DoubleAnimotion, the attached properties Storyboard.TorgetName 
and Storyboard.TorgetProperty indicate the object and property to animate. In code, ifs a little differ¬ 
ent: You continue to use the static method Storyboard.SetTargetProperty to set the property name, 
but you use Storyboard.SetTarget — not Storyboard.SetTorgetNome — to set the target object rather 
than the XAML name of the target object. If the target object is a TextBlock in XAML with the name 
"txtblk," the SetTarget call would look like this: 

Storyboard .SetTarget(anima, txtblk); 

It’s the object variable name, not the text name. In this code example I’ve set the target object to the 
Button generating the Click event. 


Also notice how the Duration property is set. Using a TimeSpan is the most common approach, 
but Duration also has two static properties: Automatic (which means one second in this context) and 
Forever (which is not recommended because it makes the animation infinitely slow). The default value 
is Automatic, which is handy if you forget to specify it. 
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Because the change in each Font Size affects the size of each Button, the Grid needs to recalculate 
the width and height of its cells. It’s fun to get all the animations going at once to watch how the Grid 
changes size: 


Trigger! 

Trigger! 

Trigger! 

Trigger! 

! Trigger! 

Trigger! 


Trigger! Trigger! Trigger! 


Other Double Animations 


A DoubleAnimation can animate any property of type double that’s backed by a dependency 
property, for example, Width or Height (or both): 

Project: EllipseBlobAnimation I File: MainPage.xaml (excerpt) 

<Page … > 


<Page.Resources 〉 

<Storyboard x: Key="storyboard" 

RepeatBehavior=" Forever" 

AutoReverse="True"> 

<DoubleAnimation Storyboard .TargetName="el 1ipse" 

Storyboard .TargetProperty="Wi dth" 

EnableDependentAnimati on="T rue" 
From="100" To="600" Durati on="0 :0:1" /> 

<DoubleAnimation Storyboard .TargetName="el 1ipse" 

Storyboard .TargetProperty="Hei ght" 

EnableDependentAnimati on="T rue" 
From="600" To="100" Durati on="0 :0:1" /> 

</Storyboard> 

</Page.Resources 〉 
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<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
〈Ellipse Name="el 1ipse"> 

〈 Ellipse.Fill 〉 

<LinearGradientBrush> 


<GradientStop 0ffset="0" Color="Pink" /> 
<GradientStop Offset="l" Color="LightBlue" /> 
</LinearGradientBrush> 

</El1ipse.Fi11 > 

</El1ipse> 

</Grid> 

</Page> 


The two animations run in parallel. The first animates the Width of the Ellipse from 100 to 600, 
and the second animates the Height of the Ellipse from 600 to 100. The two dimensions only briefly 
meet up in the middle to make a circle. The settings oi AutoReverse and RepeotBehovior can be set on 
either the Storyboard (as I’ve done) or on the individual animations. 

The animation is triggered when the page is loaded, and it runs "forever ”： 


Project: EllipseBlobAnimation I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

public MainPageO 

{ 

this. Initi alizeComponent(); 

Loaded += (sender, args)=> 

{ 

(thi s .Resources ["storyboard"] as Storyboard) .Begin(); 

}； 
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Because the LinearGradientBrush that colors the Ellipse has a default gradient from the upper-left 
corner of a bounding rectangle to the lower-right corner, the gradient actually shifts a bit during the 
animation: 



Width and Height aren’t the only properties of Ellipse that can be animated. The StrokeThickness 
property defined by Shape is also a double and is backed by a dependency property. Here's an Ellipse 
with a dotted line around its circumference, and the animation targets the thickness of that dotted 
line: 


Project AnimateStrokeThickness | File: MainPage.xaml (excerpt) 

<Page … > 

<Page.Resources 〉 

<Storyboard x: Key="storyboard"> 

<DoubleAnimation Storyboard .TargetName="el 1ipse" 

Storyboard.TargetPrope rty=" StrokeThickness" 
EnableDependentAnimati on="T rue" 

From="l" To="100" Duration="0:0:4" 
AutoReverse="True" 

RepeatBehavior="Forever" /> 

</Storyboard> 

</Page.Resources 〉 


<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

〈Ellipse Name="elli pse" 

Stroke="Red" 

StrokeDashCap=" Round" 

StrokeDashArray="0 2" /> 

</Gri d> 

</Page> 

The animation is triggered during the Loaded event with the same code as the previous program. 
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The "0 2 〃 value of the StrokeDoshArray indicates that the dashed line consists of a dash that 
is zero units long followed by a gap two units long, where these units indicate multiples of the 
StrokeThickness. This dash has rounded ends benefit of the Stroke Dash Cap property, and the rounded 
ends add to the length of the dash, so the dash actually becomes a dot with a diameter equal to the 
StrokeThickness. The centers of these dots are separated by a gap equal to twice the StrokeThickness, 
so the dots themselves are separated by the StrokeThickness. 

In this animation, the number of dots actually decreases and then increases as the StrokeThickness 
is increased and decreased by the animation. The dots seem to disappear and reappear at the far 
right of the Ellipse: 



Can you find another property of Ellipse of type double? How about StrokeDoshOffset, which 
indicates where the dashes and gaps of a dotted line begin in a dashed line? Here’s some XAML that 
uses a Path with Bezier curves to draw an infinity sign with dotted lines. The animation targets Stroke- 
DoshOffset to make the dots seem to travel around the figure: 

Project: AnimateDashOffset | File: MainPage.xaml (excerpt) 

<Page … > 

<Page.Resources 〉 

<Storyboard x: Key="storyboard"> 

<DoubleAnimation Storyboard .TargetName="path" 

Storyboard.TargetPrope rty=" StrokeDashOffset" 

EnableDependentAnimati on="T rue" 

From="0" To="1.5" Durati on="0 :0:1" 

RepeatBehavior=" Forever" /> 

</Storyboard> 

</Page.Resources 〉 
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<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Viewbox> 


〈Path Name="path" 

Margin="12" 

Stroke="{Stati cResource ApplicationForegroundThemeB rush}" 
StrokeThi ckness="24" 


StrokeDashArray="0 1.5 
StrokeDashCap=" Round" 


Data="M 100 0 

C 45 0, 

S 45 200, 
S 200 150, 
S 345 0, 

S 500 45, 

S 455 200, 
S 300 150, 
S 155 0, 


0 45, 
100 200 
250 100 
400 0 
500 100 
400 200 
250 100 
100 0 " 


</Viewbox> 


0 100 


/> 


</Gri d> 


</Page> 


Unfortunately, I can’t show the dots traveling around the infinity sign on the printed page: 



The Path definition in this program incorporates a well-known Bezier approximation to a quarter 
circle. For a circle centered at the point (0, 0), the lower-right quarter-circle arc begins at (100, 0) and 
ends at (0, 100). This can be approximated very well with a Bezier curve that also begins at (100, 0) 
and ends at (0,100) with two control points (100, 55) and (55, 100). You can draw an entire circle us¬ 
ing four of these "Bezier 55” arcs. 

Thus, the quarter-circle arc that begins this infinity sign at the upper-left corner starts at (100, 0) 
and ends at (0,100), but the center is (100, 100) rather than (0, 0), so the first control point is 55 units 
to the left of (100, 0), and the second is 55 units above (0, 100), or (45, 0), and (0, 45). The next Bezier 
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should continue the figure around the lower-left corner starting at (0,100) — the end of the previous 
Bezier — and ending at (100, 200) with control points (0, 155) and (45, 200). But the remainder of the 
path markup geometry continues not with figures indicated by C, which stands for "Cubic Bezier," but 
with S, which stands for "Smooth Bezier.’’ It is well known that two connected Bezier curves have a 
smooth connection if their common point and two adjacent control points are collinear (that is, lie on 
the same line). The S figure in path markup syntax causes the first control point to be automatically 
derived so that it is collinear with the start point and previous control point and the same distance 
from the start point as the previous collinear point. Thus, based on the point (0, 45) and (0,100) in the 
first Bezier curve, the first S figure derives the first control point to be (0,155). 

When drawing a dashed line whose end connects back with its beginning, it is very likely that 
there will be a discontinuity at the start point where only a partial dash will be displayed. The 
StrokeThickness of 24 was derived experimentally and need not necessarily be a whole number. For 
the Windows Phone version of this program, I settled upon a StrokeThickness of 23.98. 

When exploring the rest of the Shapes library for properties of type double to animate, you’ll also 
discover the XI, Yl, X2, and Y2 properties of Line. Later in this chapter I’ll demonstrate how to animate 
properties of type Point that show up in many of the PathSegment derivatives. 

The Opacity property is a very common animation target, and it’s used to fade elements in and 
out. You can set Opacity to a value ranging from 0 (transparent) to 1 (opaque). Here’s an Opacity 
animation based on John Tenniel’s illustrations of the Cheshire Cat for the original edition of Lewis 
CarrolTs Alice's Adventures in Wonderland (1865): 


Project: CheshireCat I File: MainPage.xaml (excerpt) 

<Page … > 


<Page.Resources 〉 

<Storyboard x: Key="storyboard"> 

<DoubleAnimation Storyboard .TargetName="image2" 

Storyboard.TargetPrope rty="0paci ty" 
From="0" To="l" Duration="0:0:2" 
AutoReverse="True" 

RepeatBehavior=" Forever" /> 

</Storyboard> 

</Page.Resources> 


<!-- Images from Project Gutenberg Book #114 
http://www.gutenberg.org/ebooks/114 

]ohn Tenniel's illustrations for Lewis Carrol 1's "Alice in Wonderland"--> 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

<Viewbox> 

<Gri d> 

clmage Source="Images/al ice23a.gif" 

Width="640" /> 

<TextBlock FontFami ly="Century School book" 

FontSi ze="24" 

Foreground:" Black" 

TextWrappi ng="Wrap" 
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TextAli gnment="3usti fy" 

Width="320" 

Margin="0 0 24 60" 

HorizontalA1i gnment="Ri ght" 

VerticalAli gnment="Bottom"> 

&#x2003;&#x2003;"A11 right，" said the Cat; and this 
time it vanished quite slowly, beginning with the end 
of the tail, and ending with the grin, which 
remained some time after the rest of it had gone. 

<LineBreak /> 

<LineBreak /> 

&#x2003;&#x2003;"Wei 1! I've often seen a cat without a 
grin," thought Alice; "but a grin without a cat! It's 
the most curious thing I ever saw in all my life!" 
</TextBlock> 


<Image Name="image2" 

Source="Images/a1 ice24a.gi f" 

Stretch="None" 

VerticalA1i gnment="Top"> 

<Image.Clip> 

<RectangleGeometry Rect="320 70 320 240" /> 
</Image.Clip> 

</Image> 

</Grid> 

</Viewbox> 

</Grid> 

</Page> 


As the comment in the XAML file indicates, I obtained the images from Project Gutenberg. In 
the original edition of Alice’s Adventures in Wonderland, the two images were both the width of the 
page, but the first image also extended to the full height of the page to show Alice standing by the 
tree. The images on the Project Gutenberg site, however, don’t have the same width. The first image 
(alice23a.gif) is 342 x 480 pixels and the second (alice24a.gif) is 640 x 435. When I forced them to 
have the same rendered width, they seemed to line up very well considering that they’re definitely 
two different drawings. Still, I decided to use a rectangular clipping area to restrict the second image 
to only the disappearing cat. The text that I added is not the same as that which appeared in this spot 
in the original edition. 


346 PART Elementals 



The utility of DoubleAnimotion increases enormously when you begin animating the classes 
that derive from Transform. This is a subject for the next chapter (Chapter 10, "Transforms”). You 
might remember the RainbowEight program from Chapter 3 that animated the Offset property 
of 15 GrocJientStop objects in tandem. You can do a similar program using 15 DoubleAnimotion 
objects, but in the next chapter 111 show you how to do it with one DoubleAnimotion animating a 
TronsloteTransform set on the LineorGrodientBrush. 


Animating Attached Properties 


One of the simple uses of transforms that I’ll explore in the next chapter involves moving an object 
around the screen. But you don’t need transforms for that. You can put the object in a Canvas and 
animate the Convos.Left and Convos.Top attached properties. Animating attached properties requires 
a special syntax for Storyboord.TargetProperty, as shown here: 


Project: AttachedPropertyAnimation I File: MainPage.xaml (excerpt) 
<Page … > 


<Page.Resources 〉 

<Storyboard x: Key="storyboard"> 

<DoubleAnimation Storyboard .TargetName="el 1ipse" 

Storyboard.TargetProperty=" (Canvas.Left) 
From="0" Duration="0:0: 2.51" 
AutoReverse="True" 

RepeatBehavior=" Forever" /> 
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<DoubleAnimation Storyboard .TargetName="el 1ipse" 

Storyboard.TargetProperty=" (Canvas.Top) 
From="0" Duration="0:0: 1.01" 
AutoReverse="T rue" 

RepeatBehavior=" Forever" /> 

</Storyboard> 

</Page.Resources 〉 


<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
cCanvas Si zeChanged="OnCanvasSi zeChanged" 

Margin="0 0 48 48"> 

〈Ellipse Name="el1 ipse" 

Width="48" 

Height="48" 

Fill="Red" /> 

</Canvas> 

</Gri d> 

</Page> 


The Canvas. Left and Canvas .Top attached properties are simply enclosed in parentheses. The target is 
an Ellipse colored red and hence easily recognizable as a ball. 

Notice the absence of an EnableDependentAnimotion setting. This indicates that these animations 
do not occur in the user interface thread. If you’re unsure whether to use EnableDependentAnimotion, 
try leaving it out. If the animation works, it’s OK! 

This Storyboard has two DoubleAnimation children that run in synchronization. Notice that each of 
these DoubleAnimation definitions has AutoReverse set to True and RepeotBehovior set to Forever and 
Duration values set to 1.01 seconds and 2.51 seconds, respectively. I chose prime numbers here (101 
and 251) to avoid repetitive patterns. The two animations include From values but no To values. That 
happens in the code-behind file: 

Project: AttachedPropertyAnimation I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

public MainPage() 

{ 

this. InitializeComponent(); 

Loaded += (sender, args)=> 

{ 

(thi s .Resources ["storyboard"] as Storyboard). Begin(); 

}； 

} 

void OnCanvasSizeChanged (ob ject sender, SizeChangedEventArgs args) 

{ 

Storyboard storyboard = this. Resources ["storyboard"] as Storyboard ; 

// Canvas.Left animation 

DoubleAnimation anima = storyboard.Chi 1dren[0] as DoubleAnimation; 

anima.To = args■NewSize.Width; 
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// Canvas.Top animation 

anima = storyboard.Chi 1dren[1] as DoubleAnimation ; 
anima.To = args.NewSize.Height; 



The storyboard is started in the Loaded event handler. Whenever the size of the Canvas changes 
(which happens when the size of the window changes), new To values are calculated based on the 
height and width of the Canvas, which has a Margin setting in the XAML file to compensate for the 
size of the Ellipse. You might assume that you wouldn’t be allowed to change values of an ongoing 
animation, but it seems to work fine. The effect is a ball that appears to bounce between the edges of 
the screen: 



Both DoubleAnimation definitions include the same AutoReverse and RepeotBehovior settings. 
As I mentioned earlier, these properties are defined by Timeline, which is also the parent class to 
Storyboard. Might these two settings be moved to the Storyboard tag? Try it: 


<Storyboard x : Key="storyboard" 

AutoReverse="True" 

Repeat Behavior="Forever"> 

<DoubleAnimation Storyboard.TargetName="el 1ipse" 

Storyboard.TargetProperty=" (Canvas.Left) 
From= M 0" Duration="0:0: 2.51" /> 

<DoubleAnimation Storyboard.TargetName="el 1ipse" 

Storyboard.TargetProperty=" (Canvas.Top)" 
From="0" Duration="0:0:1.01" /> 

</Storyboard> 
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This is perfectly legal, but it doesn’t work the same as the previous markup. The duration of a 
Storyboard is the duration of the longest animation child of that Storyboard, which in this case is 2.51 
seconds. The animation begins by moving the ball both horizontally and vertically. But at the end 
of 1.01 seconds, the ball hits an edge. In landscape mode, this is the bottom edge. The animation of 
the Canvos.Top property has completed, but the animation of Canvas.Left continues to move the ball 
horizontally for another 1.5 seconds. At that point the ball is in the lower-right corner of the screen. 
Both animations have now completed, so the Storyboard reverses the animation we’ve just seen until 
the ball is in the upper-left corner again. Then that same pattern repeats forever. 


Only if all the animations in a Storyboard are the same length can the AutoReverse and 
RepeatBehovior properties be moved to the Storyboard. 


The Easing Functions 

Suppose a DoubleAnimation has a From value of 100, a 7b value of 500, and a Duration of five 
seconds. By default the DoubleAnimation is linear, which means that the target property takes on 
values from 100 through 500 based on a linear relationship with elapsed time: 


Time 

Value 

0 sec 

100 

1 

180 

2 

260 

3 

340 

4 

420 

5 

500 


Or, perhaps more clearly: 


Value = From+ - x (To - From) 

Duration 

The purpose of the easing functions is to make this more interesting. 

I was originally planning to begin this discussion by demonstrating how to derive from 
EosingFunctionBase to create a custom easing function, but for reasons that I’m sure are very good 
reasons, you cannot derive from EosingFunctionBase. If you were able to, you could create your own 
easing function by simply overriding the Ease method and implementing a transfer function. The Ease 
method has a double argument that ranges from 0 to 1. The method returns a double value. When 
the argument is 0 ; the method returns 0. When the argument is 1, the method returns 1. In between, 
anything goes. In this way, the easing function effectively bends time so that the relationship between 
elapsed time and the animation value becomes nonlinear. 
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When an easing function is in effect, the elapsed time is normalized to a value between 0 and 1 
by dividing by the Duration (just as in the formula above). The Ease function is called, and the return 
value is used to calculate a value: 


Value = From +Ease 


Time 


Duration 


x (To-From) 


For example, the Exponential Ease function with the default EosingMode setting of EaseOut has this 
transfer function: 


t ， 


1-e 


-Nt 


1-e 


where t is the argument to the Ease function, t' is the result, and N is the setting of the Exponent 
property. If N equals 2 (the default value), the animation shown in the table above is instead like this: 


Time 

t 

X' 

Value 

0 sec 

0.0 

0.000 

100 

1 

0.2 

0.381 

252 

2 

0.4 

0.637 

355 

3 

0.6 

0.808 

423 

4 

0.8 

0.923 

469 

5 

1.0 

1.000 

500 


It’s faster at the beginning and then seems to slow down. 


The AnimationEaseGrapher program provides a visual representation of the easing functions and 
lets you experiment with them: 
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The graph is the transfer function with the horizontal access representing t from 0 to 1, and the 
vertical access representing t' with 0 at the top and 1 at the bottom. The dotted line from upper 
left to lower right is a linear transfer function, and the blue line is the selected transfer function. The 
points of that Polyline are assigned from the code-behind file by repeatedly calling the Ease method 
of the selected easing class. When you press the Demo button, the little red ball in the upper-left 
corner is animated horizontally with a regular linear animation and animated vertically with the se¬ 
lected ease function, and — amazingly enough — it follows the graph. 

Here’s the program’s XAML file with the animation for the red ball defined at the top. The easing 
function for this animation is assigned from the code-behind file. The To and From values are adjusted 
based on the 6-pixel radius of the ball (which appears way down at the bottom): 


Project: AnimationEaseGrapher I File: MainPage.xaml (excerpt) 

<Page … > 

<Page.Resources 〉 

<Storyboard x : Key="storyboard" 

FillBehavi or="Stop"> 

<DoubleAnimation Storyboard.TargetName=" redBal1" 

Storyboard.TargetProperty=" (Canvas.Left) 
From="-6" To="994" Duration="0:0: 3" /> 

<DoubleAnimation x:Name="ani ma2" 

Storyboard.TargetName=" redBal1" 
Storyboard.TargetProperty=" (Canvas.Top)" 
From="-6" To="494" Duration="0:0: 3" /> 

</Storyboard> 

</Page.Resources 〉 


<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Grid.ColumnDefinitions> 

<ColumnDefinition Wi dth="Auto" /> 

<ColumnDefinition Width="*" /> 

</Grid.ColumnDefinitions> 

<!-- Control panel --> 

<Grid Grid.Col umn="0" 

VerticalA1i gnment="Center"> 

<Grid.RowDefinitions> 

〈RowDefinition Height="*" /> 

〈RowDefinition Height="*" /> 

〈RowDefinition Height:"*" /> 

</Grid.RowDefinitions> 

<Grid.ColumnDefinitions> 

<ColumnDefinition Wi dth="Auto" /> 

<ColumnDefinition Wi dth="Auto" /> 

</Grid.ColumnDefiniti ons> 

<!-- Easing function (populated by code)--> 

<StackPanel Name="easi ngFunctionStackPanel" 

Grid.Row=__0" 

Grid■RowSpan="3" 

Grid.Col umn="0" 

VerticalAli gnment="Center"> 
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<RadioButton Content="None" 

Margin="6" 

Checked="OnEasi ngFunctionRadioButtonChecked" /> 

</StackPanel> 


<!-- Easing mode --> 

<StackPanel Name="easi ngModeStackPanel" 

Grid.Row="0" 

Grid.Col umn="l" 

HornzontalAli gnment="Center" 

VerticalAli gnment="Center"> 

<RadioButton Content="Ease In" 

Margin="6" 

Checked="OnEasi ngModeRadioButtonChecked ”〉 
<RadioButton.Tag> 

<Easi ngMode>EaseIn</Easi ngMode> 

</RadioButton.Tag> 

</RadioButton> 


<RadioButton Content="Ease Out" 

Margin="6" 

Checked="OnEasi ngModeRadioButtonChecked"> 
<RadioButton.Tag> 

<Easi ngMode>EaseOut</Easi ngMode> 

</RadioButton.Tag> 

</RadioButton> 


<RadioButton Content="Ease In/Out" 

Margin="6" 

Checked="OnEasi ngModeRadioButtonChecked"> 
<RadioButton.Tag> 

<Easi ngMode>EaseInOut</Easi ngMode> 

</RadioButton.Tag> 

</RadioButton> 

</StackPanel> 


<!-- Easing properties (populated by code)--> 

<StackPanel Name="properti esStackPanel" 

Grid.Row="l" 

Grid.Col umn="l" 

HornzontalAli gnment="Center" 

VerticalA1i gnment="Center" /> 

<!-- Demo button --> 

〈Button Grid. Row="2" 

Grid.Column="l" 

Content="Demo ! " 

HorizontalAli gnment="Center" 

VerticalAli gnment="Center" 

Cl ick="OnDemoButtonClick" /> 

</Gri d> 

<!-- Graph using arbitrary coordinates and scaled to window --> 
<Viewbox Grid.Col umn="l"> 

〈Grid Width="1000" 

Height="500" 

Margin="0 250 0 250"> 
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<!-- Rectangle outline --> 

〈Polygon Points="0 0, 1000 0, 1000 500, 0 500" 

Stroke="{Stati cResource ApplicationForegroundThemeBrush} 
StrokeThickness="3" /> 


<Canvas> 

<!-- Li near transfer --> 

〈Polyline Points="0 0, 1000 500" 

Stroke="{StaticResource ApplicationForegroundThemeBrush}" 
StrokeThi ckness="l" 

StrokeDashArray="3 B" /> 

<!-- Points set by code based on easing function --> 

<Polyline Name="polyline" 

Stroke="Bl ue" 

StrokeThickness="3" /> 

<!-- Animated ball --> 

〈Ellipse Name="redBall " 

Width= ,, 12" 

Height="12" 

Pill= n Red" /> 

</Canvas> 

</Grid> 

</Viewbox> 

</Gri d> 

</Page> 

The code-behind file uses reflection to obtain all the classes that derive from EasingFunction- 
Base and creates a RadioButton element for each one. When one is selected, reflection also comes 
to the rescue to obtain a parameterless constructor for the class. This allows the class to be in¬ 
stantiated. Additional reflection lets the program obtain all the public properties the particular 
Easing Function Base derivative has defined on its own. Fortunately, all these public properties are 
restricted to int or double types, so a Slider control is created for each. 

Project: AnimationEaseGrapher I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

EasingFunctionBase easingFunction; 

public MainPageO 

{ 

this. InitializeComponent(); 

Loaded += OnMainPageLoaded; 

} 


void OnMainPageLoaded(object sender, RoutedEventArgs args) 

{ 

Type baseType = typeof (Easi ngFuncti onBase) ; 

Typelnfo baseTypelnfo = baseType.GetTypelnfoO; 
Assembly assembly = baseTypelnfo.Assembly; 

// Enumerate through all Windows Runtime types 
foreach (Type type in assembly.ExportedTypes) 
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Typelnfo typelnfo = type.GetTypelnfoO; 


// Create RadioButton for each easing function 
if (typelnfo.IsPublic && 

baseTypelnfo.IsAssignableFrom(typelnfo) && 
type != baseType) 

{ 

RadioButton radioButton = new RadioButton 

{ 

Content = type.Name, 

Tag = type, 

Margin = new Thi ckness(6) , 

}； 

radioButton.Checked += OnEasingFunctionRadioButtonChecked; 
easingFunctionStackPanel.Chi Idren.Add(radi oButton); 

} 

} 

// Check the first RadioButton in the StackPanel (the one labeled "None") 
(easingFunctionStackPanel.Chi 1dren[0] as RadioButton) .IsChecked = true; 


void OnEasingFunctionRadioButtonChecked(object sender, RoutedEventArgs args) 

{ 

RadioButton radioButton = sender as RadioButton; 

Type type = radioButton.Tag as Type; 

easingFunction = null; 

propertiesStackPanel.Children.Cl ear(); 

// type is only null for "None" button 
if (type != null) 

{ 

Typelnfo typelnfo = type.GetTypelnfoO ； 


// Find a parameterless constructor and instantiate the easing function 
foreach (Const ructorlnfo constructorlnfo in typelnfo.DeclaredConstructors) 

{ 

if (constructorlnfo.IsPublic && constructorlnfo.GetParameters().Length == 0) 

{ 

easingFunction = constructorlnfo.Invoke (nul 1 ) as EasingFunctionBase ; 
break; 


// Enumerate the easing function properties 

foreach (Propertylnfo property in typelnfo.DeclaredProperties) 

{ 

// We can only deal with properties of type int and double 
if (property.PropertyType != typeof(int) && 
property.PropertyType != typeof(doubl e)) 

{ 

continue; 
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// Create a TextBlock for the property name 
TextBlock txtblk = new TextBlock 
{ 

Text = property.Name + " : " 

}； 

propertiesStackPanel.Children.Add(txtblk); 

// Create a Slider for the property value 
Slider slider = new Slider 
{ 

Width = 144, 

Minimum = 0, 

Maximum = 10, 

Tag = property 

}； 

if (property.PropertyType == typeof (i nt)) 

{ 

slider.StepFrequency = 1; 

slider.Value = (i nt)property.GetValue(easingFunction); 

} 

el se 

{ 

slider.StepFrequency = 0.1; 

slider.Value = (doubl e) property.GetValue(easingFunction); 


// Define the Slider event handler right here 

siider.ValueChanged += (siiderSender, siiderArgs)=> 

{ 

Slider sliderChanging = siiderSender as Slider; 

Propertylnfo propertylnfo = siiderChanging.Tag as Propertylnfo; 

if (property.PropertyType == typeof (i nt)) 

property. SetVal ue(easi ngFuncti on ， (i nt) si i. derArgs. NewVal ue); 

else 

property.SetValue(easingFunction, (doubl e)sliderArgs.NewValue); 
DrawNewGraphO ; 

}； 

propertiesStackPanel.Children.Add(slider); 

} 

} 

// Initialize EasingMode radio buttons 

foreach (UIE1 ement child in easingModeStackPanel.Children) 

{ 

RadioButton easingModeRadioButton = child as RadioButton ; 
easingModeRadioButton.IsEnabled = easingFunction != null; 

easingModeRadioButton.IsChecked = 
easingFunction != null && 

easingFunction.EasingMode == (Easi ngMode)easi ngModeRadioButton.Tag; 

} 
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} 


DrawNewGraphO ; 


void OnEasingModeRadioButtonChecked (ob ject sender, RoutedEventArgs args) 

{ 

RadioButton radioButton = sender as RadioButton ; 

easingFunction.EasingMode = (Easi ngMode) radioButton.Tag; 

DrawNewGraphO ； 

} 

void OnDemoButtonCli ck(object sender, RoutedEventArgs args) 

{ 

// Set the selected easing function and start the animation 
Storyboard storyboard = this .Resources ["storyboard"] as Storyboard ; 
(storyboard.Children[l] as DoubleAnimati on) .EasingFunction = easingFunction; 
storyboard.Begin(); 

} 

void DrawNewGraphO 
{ 

polyline.Points.Clear(); 

if (easingFunction == null) 

{ 

polyline.Points.Add (new Point (0 ， 0)); 
polyline.Points.Add (new Point (1000 ， 500)); 
return ; 

} 

for (decimal t = 0; t <= 1; t += 0.01m) 

{ 

double x = (doubl e) (1000 * t); 

double y = 500 * easingFunction.Ease ((doubl e)t) ; 

polyline.Points.Add (new Poi nt(x, y)); 

} 



There is some redundancy in these easing functions: The QuodroticEose, CubicEase, QuarticEase, 
and QuinticEase are all special cases of the PowerEase class, and they can be duplicated with 
Power Ease by setting the Power property to 2, 3, 4, and 5, respectively. 


The above screen shot (a few pages ago) with ElosticEase shows that this particular Ease function 
returns values outside the range of 0 and 1. The same is true with BockEose. Because the transfer 
function possibly returns values less than 0 or greater than 1, the animation could take on values 
outside the range of its From and To settings. 

For many properties, this is no problem. But for some properties an exception could be raised. 
Opacity, for example, can’t be set to values less than 0 or greater than 1. Width and Height can’t be set 
to negative values, and Fontsize must be greater than 0. Applying an animation to these properties 
that results in an illegal value will raise a run-time exception. 
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Although the easing functions usually cause animations to slow down and speed up in various 
ways, it’s possible to use the easing functions in somewhat unorthodox ways. For example, SineEase 
has this transfer function when Easing Mode \s set to the default value of EaseOut: 

• / n \ 
t = sm —— t 
\2 

It’s the first quarter of a sine curve, starting fast and slowing down. For Eoseln, it’s the first quarter of a 
cosine curve but flipped around to go from 0 to 1: 



It starts slow and speeds up. 

Sine Ease with an EosingMode setting of EoselnOut is the first half of a cosine curve, adjusted to go 
from 0 to 1: 

, 1 —cos(TU) 

t - - 

2 


It starts slow, speeds up, and then slows down again. If you were to use the EoselnOut variation 
of SineEase with a DoubleAnimation applied to the Convos.Left property of an Ellipse and you set 
AutoReverse equal to True and RepeotBehovior to Forever, you would get motion that resembles a 
pendulum: slow right before and after the motion reverses, but faster in the middle. 

If you apply a similar animation to Canvas.Top but offset by half a cycle, you can move an object 
around in a circle, as the following program demonstrates: 


Project: CircleAnimation | File: MainPage.xaml (excerpt) 

<Page … > 

<Page.Resources 〉 

<Storyboard x: Key="storyboard" SpeedRati o="3"> 

<DoubleAnimation Storyboard .TargetName="bal 1" 

Storyboard.TargetProperty=" (Canvas.Left) 
From="-350" To= M 350" Durati on="0 :0:2" 
AutoReverse="True" 

Repeat Behavior="Forever"> 

<DoubleAnimation.EasingFunction> 

<SineEase Easi ngMode="EaseInOut" /> 

</DoubleAnimation.EasingFunction> 

</DoubleAnimation> 

<Doubl eAni mati on Storyboard .TargetName="bal 1 11 

Storyboard.TargetProperty=" (Canvas.Top)" 
Begi nTime="0 :0:1" 

From="-350" To="350" Durati on="0 :0:2" 

AutoReverse="True" 

RepeatBehavior="Forever"> 

<DoubleAnimation.EasingFunction> 

<SineEase Easi ngMode="EaseInOut" /> 
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</DoubleAnimation.EasingFuncti on> 
</DoubleAnimation> 

</Storyboard> 

</Page.Resources 〉 


<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

<Canvas HorizontalAli gnment="Center" 

VerticalAli gnment="Center" 

Margin="0 0 48 48"> 

〈Ellipse Name="bal 1" 

Width="48" 

Height="48" 

Fill= M Red" /> 

</Canvas> 

</Gri d> 

</Page> 

The Convos is aligned in the center but offset by the size of the ellipse, which means that the point 
(0, 0) relative to the Canvas is 24 pixels to the left and 24 pixels above the center of the window. The 
Ellipse has default zero values of Canvas.Left and Convos.Top and sits in the center. The animations 
move that Ellipse 350 pixels to the left and right and up and down. 


Notice that the second animation has a BeginTime of one second, so for the first second after the 
program is loaded, the first animation moves the ellipse horizontally from -350 pixels to 0, and then 
the second animation kicks in and begins moving the ball vertically from -350 to 0 as it is moving 
horizontally from 0 to 350. Although the easing functions are intended to slow down and speed up 
animations, the Ellipse has a constant angular velocity as it travels around in a circle. 

I’ll show you a more direct way of implementing revolution by using a RototeTronsform in the next 
chapter. 

All-XAML Animations 


Several of the programs shown so far in this chapter have triggered the Storyboard in the handler for 
the page’s Loaded event. This is handy when you need to start an animation when a program or page 
is loaded or for "demo" animations that simply run forever. 

Triggering an animation in the Loaded event can actually be done entirely in XAML using a legacy 
property named Triggers inherited from the Windows Presentation Foundation. In the long journey 
from WPF to the Windows Runtime, the Triggers property has lost virtually all its earlier functionality, 
but it can still trigger a storyboard: 

<Page.Triggers> 

<EventTrigger> 

<BeginStoryboard> 

<Storyboard … > 


</Storyboard> 
</BeginStoryboard> 
</EventTrigger> 

</Page.Triggers> 
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The Triggers property element usually appears on the root element of a XAML file, traditionally 
toward the bottom of the file, but you can actually define the Triggers property element on any an¬ 
cestor element of the animation target. 

Notice EventTrigger and BeginStoryboard. This is the only context in which you’ll see those tags. 
EventTrigger has a RoutedEvent property, but if you try setting it to anything (including the reasonable 
"Loaded" or "Page.Loaded"), you'll generate a run-time error. BeginStoryboard can have multiple 
Storyboard children. 

Here’s a program that's similar to the ManualColorAnimation of Chapter 3. The background of the 
Grid and the Foreground of a Text Block are animated from black to white in different directions. The 
two ColorAnimation objects target the Color properties of two SolidColorBrush objects: 


Project: ForeverColorAnimation I File: MainPage.xaml (excerpt) 

<Page … > 

<Grid> 

<Grid.Background 〉 

〈SolidColorBrush x : Name="gri dBrush" /> 
</Grid.Background 〉 


<TextBlock Text="Color Animation” 

FontFami1 y="Ti mes New Roman" 
FontSize="96" 

FontWei ght="Bold" 

HorizontalAli gnment="Center" 

VerticalA1i gnment="Center"> 
<TextBlock.Foreground 〉 

〈SolidColorBrush x:Name="txtbl kBrush" /> 
</TextBlock.Foreground 〉 

</TextBlock> 

</Gri d> 


<Page.Triggers> 

<EventTrigger> 

<BeginStoryboard> 

<Storyboard RepeatBehavior=" Forever" 

AutoReverse="True"> 

<ColorAnimation Storyboard .TargetName="gri dBrush" 

Storyboard.TargetPrope rty="Col or" 

From:" Black" To="White" Duration="0:0: 2" /> 

〈ColorAnimation Storyboard .TargetName="txtbl kBrush" 

Storyboard.TargetPrope rty="Col or" 

From="Whi te" To="Bl ack" Duration="0:0: 2" /> 

</Storyboard> 

</BeginStoryboard> 

</EventTrigger> 

</Page.Triggers> 

</Page> 
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ColorAnimation is perhaps the second most common animation class after DoubleAnimotion. It’s 
pretty much limited to targeting the Color property of SolidColorBrush and GrodientStop, but these 
brushes show up frequently, so it’s more versatile than it might seem. Notice the RepeotBehovior and 
AutoReverse settings in the Storyboard. 

The code-behind file contains nothing but an InitiolizeComponent call in the page’s constructor. 
What this means is that you can copy this XAML file into the editor in the XamICruncher program 
presented in Chapter 8, "App Bars and Popups,” remove the x:Closs attribute, and run the anima¬ 
tion without help from any code. XamICruncher (or another XAML-editing program) is a fine way to 
experiment with animations. 

It’s also possible to animate properties of type Point. Properties of type Point aren’t very common, 
but EllipseGeometry has a Center property of type Point. If you create a circle or ellipse using Path 
and EllipseGeometry rather than the Ellipse class, you can move it around the screen by animating 
the Center property. Unlike animating Canvas.Left and Convas.Top, this Path doesn’t need to be in 
a Canvas, and the position of the figure is specified relative to its center rather than the upper-left 
corner. 

However, you can't animate the X and Y properties of a Point value separately. Point is a structure 
rather than a class, which means it doesn’t derive from DependencyObject, which means that the X 
and Y properties aren’t backed by dependency properties. 

Properties of type Point also show up in some PothSegment derivatives: ArcSegment, 
BezierSegment, LineSegment, and QuodroticBezierSegment all have properties of type Point. 
Animating these Point properties allows you to dynamically alter graphical figures. Here’s a program 
that uses the Bezier approximation to a circle I discussed earlier but then animates all 13 points so 
that the circle deforms into a square. Just to demonstrate that the Triggers property element doesn’t 
need to be defined on the root element of the XAML file, I’ve defined it right on the Path: 


Project: SquaringTheCircle I File: MainPage.xaml (excerpt) 


<Page … > 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
cCanvas HorizontalAli gnment="Center" 

VerticalAli gnment="Center"> 

<Path Fi1 l="{StaticResource ApplicationPressedForegroundThemeB rush}" 
Stroke="{StaticResource ApplicationForegroundThemeB rush}" 
StrokeThi ckness="3" > 

〈 Path■Data> 


<PathGeometry> 


<PathFigure x:Name="bezierl" IsClosed="True"> 


<BezierSegment 
<BezierSegment 
<BezierSegment 
<BezierSegment 


x:Name="bezier2" 

x:Name="bezier3" 

x:Name="bezier4" 

x:Name="bezier5" 


/> 

/> 

/> 

/> 


</PathFigure> 


</PathGeometry> 


〈 /Path.Data 〉 
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<Path.Triggers> 

<EventTrigger> 

<BeginStoryboard> 

〈Storyboard RepeatBehavi or="Forever"> 

<PointAnimation Storyboard .TargetName="bezi erl" 

Storyboard.TargetPrope rty=" StartPoi nt" 
EnableDependentAnimati on="T rue" 

From="0 200" To="0 250" 
AutoReverse="True" /> 

<PointAnimation Storyboard .TargetName="bezi er2" 

Storyboard .TargetProperty="Poi ntl" 
EnableDependentAnimati on="T rue" 
From="110 200" To="125 125" 
AutoReverse="True" /> 

<PointAnimation Storyboard .TargetName="bezi er2" 

Storyboard .TargetProperty="Poi nt2" 
EnableDependentAnimati on="True" 
From="200 110" To="125 125" 
AutoReverse="True" /> 

<PointAnimation Storyboard .TargetName="bezi er2" 

Storyboard.TargetPrope rty=" Point3" 
EnableDependentAnimati on="T rue" 
From="200 0" To="250 0" 
AutoReverse="True" /> 

<PointAnimation Storyboard .TargetName="bezi er3" 

Storyboard .TargetProperty="Poi ntl" 
EnableDependentAnimati on="T rue" 
From="200 -110" To="125 -125" 
AutoReverse="True" /> 

<PointAnimation Storyboard .TargetName="bezi er3" 

Storyboard.TargetPrope rty=" Point2" 
EnableDependentAnimati on="T rue" 
From="110 -200" To=__125 -125" 
AutoReverse="True" /> 

<PointAnimation Storyboard .TargetName="bezi er3" 

Storyboard .TargetProperty="Poi nt3" 
EnableDependentAnimati on="T rue" 

From= M 0 -200" To="0 -250" 
AutoReverse="True" /> 

<PointAnimation Storyboard .TargetName="bezi er4" 

Storyboard .TargetProperty="Poi ntl" 
EnableDependentAnimati on="T rue" 
From="-110 -200" To=，，-125 -125" 
AutoReverse="True" /> 

<PointAnimation Storyboard .TargetName="bezi er4" 

Storyboard.TargetPrope rty= n Point2" 
EnableDependentAnimati on="True" 
From= M -200 -110" To= ，，- 125 -125" 
AutoReverse="True" /> 
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<PointAnimation Storyboard .TargetName="bezi er4" 

Storyboard.TargetPrope rty="Poi nt3" 
Enabl eDependentAm* mati on="True" 
From="-200 0" To="-250 0" 
AutoReverse="True" /> 

<PointAnimation Storyboard .TargetName="bezi er5" 

Storyboard.TargetPrope rty="Poi ntl" 
EnableDependentAnimati on="True" 
From="-200 110" To="-125 125" 
AutoReverse="True" /> 

<PointAnimation Storyboard .TargetName="bezi er5" 

Storyboard.TargetPrope rty="Poi nt2" 
EnableDependentAnimati on="True" 
From="-110 200" To="-125 125" 
AutoReverse="True" /> 


<PointAnimation Storyboard .TargetName="bezi er5" 

Storyboard.TargetPrope rty="Poi nt3" 
EnableDependentAnimati on="True" 
From="0 200" To="0 250" 


</Storyboard> 
</BeginStoryboard> 
</EventTn'gger> 

</Path.Triggers> 

</Path> 


AutoReverse="True" /> 


</Canvas> 


</Grid> 

</Page> 


Here’s the figure somewhere between a square and a circle: 



CHAPTER 9 Animation 


363 



Animating Custom Classes 


Yes, you can animate properties of custom classes. But the animatable properties must be backed by 
dependency properties. 

Here’s a class named PieSlice that derives from Path to render a pie slice such as used in pie charts. 
The custom properties are Center, Radius, Start Angle (in degrees, measured clockwise from 12:00), 
and SweepAngle (in degrees, measured clockwise from Start Angle): 


Project: AnimatedPieSlice | File: PieSlice.cs 

using System; 
using Windows.Foundation; 
using Windows.UI.Xaml; 
using Windows■UI.Xaml.Media; 
using Windows.UI.Xaml.Shapes; 


namespace AnimatedPieSlice 

{ 

public cl ass PieSlice : Path 

{ 

PathFigure pathFigure; 

LineSegment 1 ineSegment; 
ArcSegment arcSegment; 


static PieSlice() 

{ 

CenterProperty = DependencyProperty .Regi ster("Center" , 
typeof (Point) , typeof (Pi eSli ce) , 

new PropertyMetadata (new Poi nt(100, 100), OnPropertyChanged)); 

RadiusProperty = DependencyProperty .Regi ster("Radi us" , 
typeof(doubl e) , typeof (Pi eSli ce) , 
new PropertyMetadata(100 .0, OnPropertyChanged)); 

StartAngleProperty = DependencyProperty. Regi ster("StartAngl e" , 
typeof(doubl e) , typeof (Pi eSli ce) , 
new PropertyMetadataCO .0, OnPropertyChanged)); 

SweepAngleProperty = DependencyProperty. Regi ster("SweepAngl e" , 
typeof(doubl e) , typeof (Pi eSli ce) , 
new PropertyMetadata(90 .0, OnPropertyChanged)); 


public Pi eSl i ce() 

{ 

pathFigure = new PathFigure { IsClosed = true }; 
lineSegment = new Li neSegment() ; 

arcSegment = new ArcSegment { SweepDirecti on = SweepDirecti on .Clockwise }; 
pathFigure.Segments.Add(1ineSegment); 
pathFigure■Segments.Add(arcSegment); 


PathGeometry pathGeometry = new PathGeometryO ; 

pathGeometry.Figures.AddCpathFigure); 

this. Data = pathGeometry; 

UpdateValues(); 
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public static DependencyProperty CenterProperty { private set; get ; } 


public static DependencyProperty RadiusProperty { private set; get ; } 

public static DependencyProperty StartAngleProperty { private set; get; } 

public static DependencyProperty SweepAngleProperty { private set; get; } 

public Point Center 

{ 

set { SetValue(CenterProperty, value); } 

get { return (Poi nt)GetValue(CenterProperty); } 

} 

public double Radi us 

{ 

set { SetValue(RadiusProperty, value); } 

get { return (doubl e)GetValue(RadiusProperty); } 

} 


public double StartAngle 


set { SetValue(StartAngleProperty, value); } 
get { return (doubl e)GetValue(StartAngleProperty) 


} 


public double SweepAngle 


set { SetValue(SweepAngleProperty, value); } 
get { return (doubl e)GetValue(SweepAngleProperty) 


} 


static void OnPropertyChanged(DependencyObject obj, 

DependencyPropertyChangedEventArgs args) 

{ 

(obj as PieSli ce) .UpdateValues(); 

} 

void UpdateValues() 


pathFigure.StartPoint = this. Center; 


double x = this .Center.X + this. Radi us * Math. Sin (Math. PI * this. StartAngle / 180); 
double y = this .Center.Y - this. Radi us * Math .Cos (Math .PI * this. StartAngle / 180); 
1ineSegment.Point = new Poi nt(x, y); 

x = this .Center.X + thi s. Radi us * Math .Sin (Math .PI * (thi s .StartAngle + 

this .SweepAngle) / 180); 

y = this .Center.Y - this .Radi us * Math .Cos (Math .PI * (thi s .StartAngle + 

this .SweepAngle) / 180); 

arcSegment.Point = new Poi nt(x, y); 
arcSegment.IsLargeArc = this. SweepAngle >= 180; 

arcSegment.Size = new Si ze(thi s .Radi us, this .Radi us); 

} 
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Just about everything in this class is overhead for the dependency properties except the 
UpdateValues method, and that method is critical. UpdateValues is called whenever any of the four 
properties changes. Any of those four properties can be the target of an animation, which means that 
UpdateValues might be called 60 times per second for an indefinite period of time. 

In methods called so frequently you should be careful about creating objects that require memory 
allocations on the heap. Creating new double and Point values is fine because those are stored on the 
stack. But a not very good way to implement this method would be to create new PathFigure, Line- 
Segment, and ArcSegment objects during every call because that generates a lot of activity allocating 
memory that must later be freed. Try re-using or caching objects rather than re-creating them. 

The PieSlice class is part of the AnimatedPieSlice project, which includes a MainPage.xaml that 
instantiates, initializes, and animates it: 


Project: AnimatedPieSlice I File: MainPage.xaml (excerpt) 

<Page … > 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

<1ocal : PieSlice x:Name="pi eSlice" 

Center="400 400" 

Radius="200" 

Stroke="Red" 

StrokeThi ckness="3" 

Fill="Yellow" /> 

</Gri d> 

<Page.Triggers> 

<EventTrigger> 

<Begi nStoryboard> 

<Storyboard> 

<DoubleAnimation Storyboard.TargetName="pi eSlice" 

Storyboard .TargetProperty="SweepAngl e" 

EnableDependentAnimation="True" 

From="l" To="359" Duration="0:0: 3" 
AutoReverse="True" 

RepeatBehavior="Forever" /> 

</Storyboard> 

</BeginStoryboard> 

</EventTrigger> 

</Page.Triggers> 

</Page> 

The result is a pie slice that ranges from 1 degree to 359 degrees, back and forth forever: 
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Key Frame Animations 


All the programs you’ve seen so far have animated properties from one value to another, usually 
specified as the From and To properties of DoubleAnimation, ColorAnimotion, and PointAnimo- 
tion classes, and the only variations have involved nonlinear ways to get from From to To and then 
reversing animations to go from To to From. 

What if you need to animate a property from one value to another value and then to a third value, 
and maybe even beyond? A solution that might occur to you is to define several animations in the 
storyboard targeting the same property and to use BeginTime to delay some of those animations so 
that they don’t overlap. But that’s illegal. You can’t have more than one animation in a storyboard 
targeting a particular property. 

The correct solution is a key frame animation, so called because you define the progress of the 
animation through a series of key frames. Each key frame indicates what the value of the property 
should be at a particular elapsed time and how to get from the previous key frame value to the new 
value in that key frame. 

Here’s a simple example of a key frame animation that targets the Center property of an 
EllipseGeometry to move the circle around the screen: 

Project: SimpleKeyFrameAnimation | File: MainPage.xaml (excerpt) 

<Page … > 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

〈Path Fill="Blue"> 

〈 Path■Data> 

<E11ipseGeometry x:Name="el 1ipse" 

RadiusX="24" 

RadiusY="24" /> 
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〈 /Path.Data 〉 
</Path> 

</Gri d> 


<Page.Triggers> 

<EventTrigger> 

<BeginStoryboard> 

<Storyboard> 

<PointAnimationUsingKeyFrames Storyboard.TargetName="el 1ipse" 

Storyboard.TargetPrope rty="Center" 
EnableDependentAnimation="T rue" 
RepeatBehavi or="Forever"> 

<DiscretePointKeyFrame KeyTime="0:0:0" Val ue="100 100" /> 

<LinearPointKeyFrame KeyTime="0:0:2" Val ue="700 700" /> 

<LinearPointKeyFrame KeyTime="0: 0:2.1" Val ue="700 100" /> 

<LinearPointKeyFrame KeyTime="0:0:4.1" Val ue="100 700" /> 

<LinearPointKeyFrame KeyTime="0:0:4.2" Val ue="100 100" /> 
</PointAnimationUsingKeyFrames> 

</Storyboard> 

</BeginStoryboard> 

</EventTrigger> 

</Page.Triggers> 

</Page> 


Rather than a PointAnimation, the Storyboard contains a PointAnimotionUsingKeyFromes. 

Rather than specifying From, To, and Duration properties in the PointAnimation, the 
Poin tAnimotion Using Key Frames contains children of type DiscretePoin tKey From e and 
Lin ear Poin tKeyFrome. 

Each key frame in a collection specifies what you want the value of the target property to be at 
that particular time from the beginning of the animation. Very often a collection of key frames will 
begin with a Discrete item with a KeyTime of zero, basically initializing the property to that value: 

<DiscretePointKeyFrame KeyTime="0:0:0" Val ue="100 100" /> 

The next key frame in the collection is 

<LinearPointKeyFrame KeyTime="0:0:2" Val ue="700 700" /> 

What this means is that the target property is linearly increased from the previous point (100,100) to 
the point (700, 700) over the course of two seconds. At an elapsed time of two seconds, the value is 
(700, 700). 


The next key frame specifies a much faster animation: 

<LinearPointKeyFrame KeyTime="0:0:2.1" Val ue="700 100" /> 

From an elapsed time of two seconds to 2.1 seconds, the point changes from (700, 700) to (700, 100). 
The animation then slows up again for the next two seconds: 

<LinearPointKeyFrame KeyTime="0:0:4.1" Val ue="100 700" /> 

The last key frame is: 


368 PART Elementals 



<LinearPointKeyFrame KeyTime="0:0:4.2" Val ue="100 100" /> 

At an elapsed time of 4.2 seconds, the value of the target property is (100,100) and the animation is 
finished. At this point, it can reverse AutoReverse is true) or start over again (if an appropriate value 
of RepeotBehovior is set). 

It’s possible for programmers to "overthink" key frames, so here are two extraordinarily simple 
rules that might prevent confusion: 

■ A key frame always indicates the desired value of the property at that elapsed time. 

■ The duration of an animation is the highest key time in the collection. 


To store the collection of key frames, the Point A n i motion UsingKeyFromes class defines a property 
named KeyFrames of type PointKeyFromeCollection, which is a collection of PointKeyFrame objects. 
PointKeyFrome defines the KeyTime and Value properties. Four classes derive from PointKeyFrame, 
and you’ve already seen two of them: 

■ DiscretePointKeyFrame jurr\ps to a particular value. 

■ Line orPoin t Key From e performs a linear animation. 

■ Spline PointKeyFrame can speed up or slow down. 

■ Easing PointKeyFrame animates with an easing function. 

Similarly, the Windows Runtime includes a DoubleAnimationUsingKeyFrames class, which has 
children of type DoubleKeyFrome, from which similar Discrete, Linear, Spline, and Easing classes derive, 
and ColorAnimo tion Using Key Frames with children of type ColorKeyFrame, also with Discrete, Linear, 
Spline, and Easing derivatives. 

The following project uses ColorAnimotionUsingKeyFromes to color the background of the grid 
with colors that animate through the rainbow: 

Project: RainbowAnimation I File: MainPage.xaml (excerpt) 

<Page … > 

<Gri d> 

<Grid.Background 〉 

<SolidColorBrush x:Name="brush" /> 

</Grid.Background 〉 

</Grid> 


<Page.Triggers> 

<EventT rigger> 

<BeginStoryboard> 

<Storyboard RepeatBehavior="Forever"> 

<ColorAnimationUsingKeyFrames Storyboard.TargetName=" brush" 

Storyboard .TargetProperty="Color"> 
<DiscreteColorKeyFrame KeyTime="0:0:0" Val ue="#FF0000" /> 

<LinearColorKeyFrame KeyTime="0:0:l" Val ue="#FFFF00" /> 

<LinearColorKeyFrame KeyTime="0:0:2" Val ue="#00FF00" /> 

<LinearColorKeyFrame KeyTime="0:0: 3" Val ue="#00FFFF" /> 

<LinearColorKeyFrame KeyTime="0:0:4" Val ue="#0000FF" /> 
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<LinearColorKeyFrame KeyTime="0:0: 5" Val ue="#FF00FF" /> 
<LinearColorKeyFrame KeyTime="0:0:6" Val ue="#FF0000" /> 
</ColorAnimationUsingKeyFrames> 

</Storyboard> 

</BeginStoryboard> 

</EventTrigger> 

</Page.Triggers> 

</Page> 


The animation is 6 seconds in length, and it ends up at the same value it started with, which means 
there won’t be any discontinuities when it starts over again from the beginning. 

Here's a pair of Poin tA n im ation Using Key From es objects that animate the Start Point and End Point 
properties of a LinearGradientBrush object to make the gradient go around in circles: 


Project: GradientBrushPointAnimation | File: MainPage.xaml (excerpt) 

<Page … > 

<Grid> 

<Grid.Background 〉 

<LinearGradientBrush x:Name="gradi entBrush% 
<GradientStop 0ffset="0" Color="Red" /> 
<GradientStop Offset="l" Color="Blue" /> 
</LinearGradientBrush> 

</Grid.Background 〉 

</Gri d> 


<Page.Triggers> 

<EventTrigger> 

<BeginStoryboard> 

<Storyboard RepeatBehavior="Forever"> 

<PointAnimationUsingKeyFrames Storyboard .TargetName="gradi entBrush" 

Storyboard.TargetPrope rty=" StartPoi nt" 
EnableDependentAnimati on="True"> 

<LinearPointKeyFrame KeyTime="0:0:0" Value="0 0" /> 

<LinearPointKeyFrame KeyTime="0:0:l" Value="l 0" /> 

<LinearPointKeyFrame KeyTime="0:0:2" Value="l 1" /> 

<LinearPointKeyFrame KeyTime="0:0: 3" Value="0 1" /> 

<LinearPointKeyFrame KeyTime="0:0:4" Value="0 0" /> 

</PointAnimationUsingKeyFrames> 


<PointAnimationUsingKeyFrames Storyboard .TargetName="gradi entBrush" 

Storyboard.TargetPrope rty=" EndPoint" 
EnableDependentAnimati on="True"> 


<LinearPointKeyFrame KeyTime="0 :0:0" 
<LinearPointKeyFrame KeyTime="0 :0:1" 
<LinearPointKeyFrame KeyTime="0 :0:2" 
<LinearPointKeyFrame KeyTime="0:0: 3" 
<LinearPointKeyFrame KeyTime="0:0:4" 
</PointAnimationUsingKeyFrames> 


Value="l 1 
Value="0 1 
Value="0 0 
Value="l 0 
Value="l 1 


/> 

/> 

/> 

/> 

/> 


</Storyboard> 


</BeginStoryboard> 
</EventTrigger> 
</Page.Triggers> 


</Page> 
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The SplineDoubleKeyFrome, SplineColorKeyFrame, and Sp I in e Po in tKey Fro m e objects are not 
used as much as they once were because much of their functionality has been superseded by 
EasingDoubleKeyFrome, EasingColorKeyFrame, and EosingPointKeyFrome. With the Spline variations of 
the key frame, you use a KeySpline object to define two control points of a Bezier spline that begins at the 
point (0, 0) and ends at (1,1). This spline performs the same role as an easing function in that it bends 
time and causes an animation to speed up and slow down. I’ll have an example in the next chapter. 

The Object Animation 

The Windows Runtime animation system is also capable of animating properties of type Object, which 
implicitly seems to encompass everything, but there’s a catch: There is no ObjectAnimation class with 
From and To properties. There is only an Object An i motion UsingKeyFromes class, and the only class 
that derives from ObjectKeyFrame is DiscreteObjectKeyFrame. 

In other words, you can indeed define an animation to target a property of any type (as long as 
that property is backed by a dependency property), but you can use the animation only to set that 
property to discrete values. 

In practice, object animations are used mostly for targeting properties of enumeration types or 
Brush types, which allows setting the property to a predefined brush resource. These are mostly used 
in control templates, as you’ll see in Chapter 11. 

But here’s an example that moves an Ellipse around a screen while animating its Visibility property 
with the enumeration members Visible and Collapsed and its Fill property with predefined brushes. 
Because these animations cause the Ellipse to flicker on and off, and with different discrete colors, the 
project is called FastNotFluid: 


Project: FastNotFluid | File: MainPage.xaml (excerpt) 

<Page … > 

<Grid Background="Gray"> 

<Canvas Si zeChanged="OnCanvasSi zeChanged" 
Margin="0 0 96 96"> 

〈Ellipse Name="el 1ipse" 

Width="96" 

Height="96" /> 

</Canvas> 

</Gri d> 


<Page.Triggers> 

<EventT rigger> 

<BeginStoryboard> 

<Storyboard> 

<DoubleAnimation x:Name="horzAni ma" 

Storyboard.TargetName="el 1ipse" 
Storyboard.TargetProperty=" (Canvas.Left) 
From= ,, 0" Du rati on="0: 0:2.51" 
AutoReverse="True" 

RepeatBehavior=" Forever" /> 
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<DoubleAnimation x : Name="vertAni ma" 

Storyboard.TargetName="el 1ipse" 

Storyboard.TargetProperty=" (Canvas.Top)" 

From="0" Duration="0:0: 1.01" 

AutoReverse="T rue" 

RepeatBehavior="Forever" /> 

<0bjectAnimationUsingKeyFrames 

Storyboard .TargetName="el lipse" 

Storyboard■TargetProperty=” Vi sibi1ity" 

RepeatBehavior=" Forever"> 

<DiscreteObjectKeyFrame KeyTime="0:0:0" Value="Visible" /> 

<DiscreteObjectKeyFrame KeyTime="0:0:0.2" Value="Col lapsed" /> 
<DiscreteObjectKeyFrame KeyTi me="0 :0:0.25" Value="Visible" /> 
<DiscreteObjectKeyFrame KeyTime="0:0:0. 3" Val ue="Col 1apsed" /> 
<DiscreteObjectKeyFrame KeyTi me="0 :0:0.45" Val ue="Vi sible" /> 
</0bjectAnimationUsingKeyFrames> 


<0bjectAnimationUsingKeyFrames 

Storyboard .TargetName="el lipse" 

Storyboard.TargetPrope rty="Fi 11" 
RepeatBehavior="Forever"> 

<DiscreteObjectKeyFrame KeyTi me="0 :0:0" 

Val ue="{Stati〔Resource ApplicationPageBackgroundThemeBrush}" /> 

<DiscreteObjectKeyFrame KeyTi me="0 :0:0.2" 

Val ue="{StaticResource ApplicationForegroundThemeBrush}" /> 

<DiscreteObjectKeyFrame KeyTime="0:0:0.4" 

Val ue="{StaticResource ApplicationPressedForegroundThemeB rush}" /> 
<DiscreteObjectKeyFrame KeyTi me="0 :0:0.6" 

Val ue="{StaticResource ApplicationPageBackgroundThemeBrush}" /> 
</0bjectAnimationUsingKeyFrames> 

</Storyboard> 

</BeginStoryboard> 

</EventTrigger> 

</Page.Triggers> 

</Page> 

It is interesting that the Value property of the DiscreteObjectKeyFrome can be set directly to the name 
of an enumeration member or set to a StoticResource without causing confusion about the type. 


Another advantage of defining the Storyboard and animations in a Triggers section is accessing the 
individual animations by name in the code-behind file: 


Project: FastNotFluid | File: MainPage.xaml.es (excerpt) 

void OnCanvasSizeChanged (ob ject sender, SizeChangedEventArgs args) 

{ 

horzAnima.To = args.NewSize.Width; 
vertAnima.To = args.NewSize.Height; 

} 
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Predefined Animations and Transitions 


I said at the outset that the Windows.Ul.Xoml.Media.Animation contained 71 classes, but if you've 
been keeping count, you probably haven’t reached that number yet. 

Besides the classes I’ve mentioned so far, the namespace also includes 14 predefined animations 
that derive from Timeline with names that end with ThemeAnimotion. These animations al¬ 
ready have all their properties and target properties set and need only a target object that you 
set with a TorgetNome property. So that you can experiment with these predefined animations, 

I’ve created a program where 12 of these animations (excluding SplitOpenThemeAnimotion and 
SplitCloseThemeAnimation, which don’t quite fit in the scheme of this program) are associated with 
their own Storyboard objects where the TargetName is set to an element with the name of "button”: 

Project: PreconfiguredAnimations | MainPage.xaml (excerpt) 

<Page … > 

<Page.Resources 〉 

<Style TargetType=" Button"> 

〈Setter Property="Margi n" Value="0 6" /> 

</Style> 


<Storyboard x: Key="fadeln"> 

<FadeInThemeAnimation TargetName=" button" /> 
</Storyboard> 


<Storyboard x: Key="fadeOut"> 

<FadeOutThemeAnimation TargetName=" button" /> 
</Storyboard> 


<Storyboard x: Key="popIn"> 

<PopInThemeAnimation TargetName=" button" /> 
</Storyboard> 


<Storyboard x: Key="popOut"> 

<PopOutThemeAnimation TargetName=" button" /> 
</Storyboard> 


<Storyboard x:Key="reposi tion"> 

<RepositionThemeAnimation TargetName=" button" /> 
</Storyboard> 


<Storyboard x:Key="poi nterllp"> 

<Poi nterllpThemeAni mati on TargetName=" button" /> 
</Storyboard> 


<Storyboard x:Key="poi nterDown"> 

<PointerDownThemeAnimation TargetName=" button" /> 
</Storyboard> 


<Storyboard x:Key="swi peBack"> 

<SwipeBackThemeAnimation TargetName=" button" /> 
</Storyboard> 
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<Storyboard x:Key="swi peHint"> 

<SwipeHintThemeAnimation TargetName=" button" /> 
</Storyboard> 


<Storyboard x: Key="dragltem"> 

<DragItemThemeAnimation TargetName=" button" /> 
</Storyboard> 


<Storyboard x: Key="dropTargetItem"> 

<DropTargetItemThemeAnimation TargetName=" button" /> 
</Storyboard> 


<Storyboard x: Key="dragOver"> 

<DragOverThemeAnimation TargetName=" button" /> 
</Storyboard> 

</Page.Resources> 


<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Grid.ColumnDefinitions> 

<ColumnDefinition Wi dth="Auto" /> 

<ColumnDefinition Width="*" /> 

</Grid.ColumnDefinitions> 


<StackPanel Name="ani mationTriggersStackPanel 
Grid.Col umn="0" 

VerticalAli gnment="Center"> 

<Button Content="Fade In" 

Tag="fadeln" 

Cli ck="OnButtonCl ick" /> 

〈Button Content="Fade Out" 

Tag="fadeOut" 

Cli ck="OnButtonCl ick" /> 


〈Button Content="Pop In" 
Tag="popIn" 

Cli ck="OnButtonCl ick" /> 

〈Button Content="Pop Out" 
Tag="popOut" 

Cli ck="OnButtonCl ick" /> 

〈Button Content="Reposi tion" 
Tag="reposi tion" 

Cli ck="OnButtonCl ick" /> 


〈Button Content="Poi nter Up" 
Tag="poi nterUp" 

Cli ck="OnButtonCl ick" /> 

<Button Content="Poi nter Down" 
Tag="poi nterDown" 

Cli ck="OnButtonCl ick" /> 
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〈Button Content="Swi pe Back" 
Tag="swi peBack" 

Cli ck="OnButtonCl ick" /> 

〈Button Content="Swi pe Hint" 
Tag="swi peHi nt" 

Cli ck="OnButtonCl ick" /> 

〈Button Content="Drag Item" 
Tag="dragltem" 

Cli ck="OnButtonCl ick" /> 

〈Button Content="Drop Target Item" 
Tag="dropTargetItem" 

Cli ck="OnButtonCl ick" /> 

〈Button Content="Drag Over" 
Tag="dragOver" 

Cli ck="OnButtonCl ick" /> 
</StackPanel> 


<!-- Animation target --> 

<Button Name="button" 

Grid.Col umn="l" 

Content="Bi g Button" 
FontSize="48" 

HorizontalA1i gnment="Center" 
VerticalAli gnment="Center" /> 

</Grid> 

</Page> 


Besides the Button named "button", the XAML file also defines a Button for each of the 
preconfigured animations. The code-behind file uses the Tog property to trigger the corresponding 
Storyboard: 

Project: PreconfiguredAnimations I File: MainPage.xaml.es (excerpt) 

void OnButtonCli ck(object sender, RoutedEventArgs args) 

{ 

Button btn = sender as Button ; 

string key = btn.Tag as string; 

Storyboard storyboard = this .Resources[key] as Storyboard ; 
storyboard.Begin(); 

} 


Watch out! Some of these animations cause the target Button to disappear, and others are 
rather subtle, but you’ll get an idea of some of the effects that you might want to add to your own 
application. 

Another set of predefined animations is the eight classes that derive from Transition. These are 
rather more complex sets of animations that you set to one of the following properties of type 
TronsitionCollection: 


■ Transitions property defined by UlElement 

■ ContentTransitions property defined by ContentControl 
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■ ChildrenTransitions property defined by Panel 

■ ItemContainerTransitions property defined by ItemsControl 

For example, try replacing the Stock Pan el tag in the Preconfigured Animations program with the 
following: 


<StackPanel Name="ani mationTriggersStackPanel" 

Grid.Col umn="0" 

VerticalAli gnment="Center"> 

<StackPanel.ChildrenTransitions> 

<TransitionCol 1ecti on> 

<EntranceThemeTransition /> 

</TransitionCol1ection> 

</StackPanel.ChildrenTransitions> 

Now, as the page is loaded, the buttons seem to appear a little offset from their actual positions and 
then shift into place. 

I’ll have more to say about these transitions in Chapter 11 and Chapter 12, "Pages and Navigation." 
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CHAPTER 10 

Transforms 


I n Chapter 9, "Animation,” you saw how to use animations to move objects around the screen, 
change their size or color or opacity, and even move the dots in a dotted line. But certain types of 
animations were missing. What if you want to use an animation to rotate a button when the button is 
clicked? And I don’t necessarily mean to make the button spin around crazy, but maybe just jiggle a 
little as if the button is saying, 〃l simply can’t restrain my enthusiasm to be carrying out the command 
you desire." 

What you need for this job (and others like it) are transforms. Back in the old days, transforms were 
called graphics transforms or even — perhaps to scare away the uninitiated — matrix transforms. But 
in recent years transforms have been liberated from the greedy clutches of the graphics mavens and 
made available to all programmers. 

This is not to imply that transforms no longer have anything to do with mathematics. (Yes, there 
will be math.) But it's possible to use transforms in the Windows Runtime without getting involved in 
the mathematics that enable their capabilities. 

A Brief Overview 


A transform is basically a mathematical formula that is applied to a point (x, y) to create a new point 
(x\ y'). If you apply the same formula to all the points of a visual object, you can effectively move the 
object, or make it a different size, or rotate it, or even distort the object in various ways. 

Transforms are supported in the Windows Runtime with three properties defined by UI Element 
RenderTronsform, RenderTransformOrigin, and Projection. Because these properties are defined by 
UlElement, transforms are not limited to vector graphics as they were in the old days. You can apply 
transforms to any element, including Image, Text Block, and Button. If you apply a transform to a Panel 
derivative such as a Grid, it also applies to all the children of that panel. 
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To apply a transform to an element, use property-element syntax to set the RenderTronsform 
property to an instance of a class that derives from Transform, for example, RototeTronsform: 


Project: SimpleRotate I File: MainPage.xaml (excerpt) 

<Crid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

<Image Sou rce="http: //www.char!espetzold.com/pw6/PetzoldJersey.jpg" 
Stretch="None" 

HorizontalAli gnment="Ri ght" 

VerticalAli gnment="Bottom"> 

<Image.RenderTransform> 

<RotateTransform Angle="135" /> 

</Image.RenderTransform> 

</Image> 

</Grid> 

The Angle property of the RotateTransform indicates a clockwise rotation of 135 degrees: 



But the result only appears reasonable because I knew that the Image would be rotated relative to 
its upper-left corner, so I deliberately positioned the Image element in the lower-right corner of the 
page. Rotation in two dimensions always occurs around a particular point — like a pin that attaches 
a photograph to a cork board — and setting that point correctly turns out to be one of the trickier 
aspects of working with transforms. 
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You can set the RenderTronsform property to any one of the seven classes that derive from 
Transform, arranged here roughly in order of increasing mathematical complexity: 

Object 

DependencyObject 

GenerolTronsform 

Transform 

TranslateTransform 

ScaleTronsform 

RototeTransform 

SkewTransform 

CompositeTronsform 

Ma trixTransform 

TransformGroup 

These classes define traditional two-dimensional affine transforms. The word "affine" suggests that 
the transformed object has certain affinities with the nontransformed object: A straight line is always 
transformed to another straight line. The line possibly assumes a different location, size, or orienta¬ 
tion, but it is still a straight line. Lines that are parallel prior to an affine transform continue to be 
parallel after the transform. An affine transform never causes anything to shoot off into infinity. 
Indeed, the mathematical definition of affine is "preserving finiteness." 

The Windows Runtime also supports a certain type of non-affine transform commonly used in 
three-dimensional perspective. You can use the Windows Runtime to achieve three-dimensional 
effects by setting the Projection property defined by UlElement to an instance of one of the two 
classes that derive from Projection: 

Object 

DependencyObject 

Projection 

PloneProjection 
Ma trix3D Projection 

Rotation in three dimensions is always around an axis. Rotation around the Y (vertical) axis is 
demonstrated in the SimpleProjection project: 


Project: SimpleProjection | File: MainPage.xaml (excerpt) 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Image Source="http://www.charl espetzold.com/pw6/PetzoldJersey.jpg" 
HorizontalA1i gnment="Center" 

VerticalAli gnment="Center"> 

<Image.Proj ecti on> 

<PlaneProjection RotationY="-60" /> 

</Image.Projection> 

</Image> 

</Grid> 
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This creates a rather different sort of rotation, seeming to add a third dimension to the two 
dimensions of the screen: 



Obviously, parallel lines are not preserved in this type of transform. That’s what makes it appear as if it 
exists in 3D space. 

The Projection transforms are sometimes called pseudo-3D transforms and are intended to provide 
a little "3Dishness 〃 to the Windows Runtime. You can define an animation to make an element seem 
to swing into view like a door or flip around like a playing card. But the element itself stays flat. This is 
why one of the Projection classes refers to a "plane.” You’re basically taking a flat element and moving 
it in 3D space. 


Math-oriented programmers might be able to persuade Matrix3DProjection to display actual 3D 
objects in the Windows Runtime. But the Windows Runtime is missing some crucial features of 3D, 
such as surface shading based on light sources, or clipping when one object is partially hidden behind 
another. If you need to bring real 3D graphics into your Windows 8 application, you’ll want to use 
Direct3D, which is only accessible from C++ and (it grieves me to say) beyond the scope of this book. 


Rotation (Manual and Animated) 

It’s common for tutorials such as this to begin the subject of transforms with the mathematically 
simple ones: TransloteTronsform to move objects and ScaleTronsform to make them larger or smaller. 
But these aren’t very impressive because you’ve already seen animations that move an object around 
the screen or change its size. That’s why I’m starting with something you can’t do in other ways. 

I just demonstrated that you can set the Angle property of RototeTronsform directly in XAML, but 
it’s much more fun to change the Angle property dynamically with a data binding or an animation, 
and the result can also be more revealing of what’s actually going on. Here’s a XAML file with the 
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Angle property of a RototeTronsform bound to the Value property of a Slider with a range from 0 
through 360: 


Project: RotateTheText I File: MainPage.xaml (excerpt) 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

〈Border BorderBrush="{Stati cResource ApplicationForegroundThemeBrush}" 

BorderThi ckness="l" 

HorizontalA1i gnment="Center" 

VerticalAli gnment="Center"> 

<Grid> 

<Grid.RowDefinitions> 

<RowDefinition Hei ght="Auto" /> 

〈RowDefi n*i ti on Height="Auto" /> 

</Grid.RowDefinitions> 

〈Slider Name="sl ider" 

Grid.Row="0" 

Minimum="0" 

Maximum="360" /> 

<TextBlock Text="Rotate Text with SIider" 

Grid.Row="l" 

FontSize="48"> 

<TextBlock.RenderTransform> 

<RotateTransform Angle="{Bi nding ElementName=sl ider, Path=Val ue}" /> 
</TextBlock.RenderTransform> 

</TextBlock> 

</Grid> 

</Border> 

</Grid> 


The Slider and TextBlock occupy two rows of a Grid that’s inside a Border. Here’s how it looks when 
the screen first comes up: 


Rotate Text with Slider 
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The TextBlock width determines the Grid width, which then determines the Slider width and the Border 
width. 

As you use the mouse or your fingers to change the Slider value, the TextBlock rotates in a 
clockwise direction. Here it is at 120 degrees: 



It’s obvious that the size of the Grid and the Border continue to be based on the unrotated TextBlock, 
and the rotated TextBlock has broken free of the boundaries of its ancestors in the visual tree. 

The property of UlElement to which you set the RototeTronsform is named RenderTronsform, and 
youll want to mull over that property name a little bit. That word render means that the transform 
affects only how the element is rendered and not how the element appears to the layout system. 
That’s a mix of good news and bad news. 

The good news is that this transform occurs at a relatively deep level in the graphics composition 
system. Rotating the TextBlock does not require that the entire visual tree be subjected to an 
updated layout. Because the layout system doesn’t get involved, transform animations can occur in a 
secondary thread and performance is very good. The layout system is completely unaware that the 
TextBlock is being rotated. 

The bad news is that the layout system is completely unaware that the TextBlock is being rotated. 
For example, you might want to display a sideways TextBlock by rotating it by 90 degrees, perhaps 
as a caption for the side of a graph. It would be most convenient if the layout system calculated the 
dimensions of the rotated TextBlock so that you could simply put it in the cell of a Grid and have the 
Grid position it properly. But that’s not possible in the Windows Runtime in any easy generalized 


manner. 


In contrast, the version of UlElement available in the Windows Presentation Foundation (WPF) 
defined both a RenderTransform property (which worked like the Windows Runtime) and a 
LayoutTronsform property, which allowed specifying a transform recognized by the layout system. 
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That LoyoutTronsform property was lost in the transition from WPF to Silverlight and the Windows 
Runtime, and mimicking it requires a bit of work. 

Let’s go back to the running RotateTheText program. Manipulate the Slider so that the TextBlock 
partially lies on top of the Slider: 




Now remove all fingers from the screen (or release the mouse button), and try touching or clicking 
the Slider in a spot where the TextBlock overlaps. The Slider doesn’t respond because the TextBlock 
is blocking the mouse or touch input. The lesson learned is this: Although the layout system doesn’t 
know that the TextBlock has moved, hit-testing logic continues to be aware exactly where it is. (On 
the other hand, while you're in the actual process of manipulating the Slider, the TextBlock doesn’t 
interfere because the Slider has captured this input, which is a concept I’ll discuss in Chapter 13, 
"Touch, Etc .’’） 

You’ll also notice that the rotation of the TextBlock is relative to its upper-left corner, which 
conceptually is the origin of the TextBlock: the point (0, 0). In many graphics systems, it is com¬ 
mon for graphics transforms to be relative to the origin of the canvas on which the graphics object 
is positioned. In the Windows Runtime, all transforms are relative to the element to which they're 
applied. 

Very often you’ll prefer that rotation be relative to some point other than the upper-left corner. 
This point is sometimes referred to as "the center of rotation,” and you can specify it in three different 
ways: 

The first way is the one that is most illuminating of the underlying mathematics of the transform, 
but I’ll save it for later. 

The second way involves the RototeTronsform class itself. The class defines CenterX and CenterY 
properties that are 0 by default. If you want this particular TextBlock to rotate relative to its center, 
set CenterX to half the width of the TextBlock and CenterY to half its height. This information can be 
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obtained during the Loaded handler, so you can add something like the following to the constructor 
of the code-behind file. Fortunately, I gave the Text Block a name even though that name isn’t used in 
the XAML file: 


public MainPage() 

{ 

this. InitializeComponentC); 

Loaded += (sender, args)=> 

{ 

RotateTransform rotate = txtblk.RenderTransform as RotateTransform; 
rotate.CenterX = txtblk.ActualWidth / 2; 
rotate.CenterY = txtblk.ActualHeight / 2; 

}； 


You might think that this approach is a bit of a hassle, so you’ll be pleased to discover that the 
third approach is much simpler. It involves the RenderTronsformOrigin property defined by UlElement. 
This property is of type Point but you set it to relative coordinates, where the X and Y values normally 
range from 0 to 1. The default is the point (0, 0), which is the upper-left corner. The point (1, 0) is the 
upper-right comer, (0, 1) is the lower-left corner, and (1, 1) is the lower-right corner. To specify an 
origin at the center of the element, use the point (0.5, 0.5): 

〈TextBlock Name="txtbl k" 

Text="Rotate Text with Slider” 

Grid.Row="l" 

FontSize="48" 

RenderTransformOrigi n="0 .5 0.5"> 

<TextBlock.RenderTransform> 

<RotateTransform Angl e="{Binding ElementName=sl ider, Path=Val ue}" /> 

</TextBlock.RenderTransform> 

</TextBlock> 


Notice that CenterX and CenterY are properties of RotateTronsform, but the RenderTronsformOri- 
gin property is defined by UlElement and common to all elements. If you set RenderTronsform Origin 
in addition to CenterX and CenterY, the effects are compounded. In this example, the compounded 
effect of both examples would cause rotation to be around the lower-right corner of the Text Block. 

You can specify a center of rotation that is outside the element. Here’s a XAML file that positions a 
TextBlock in the top center of the page and then starts up a "forever” animation to rotate it: 


Project: RotateAroundCenter | File: MainPage.xaml (excerpt) 

<Page … > 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<TextBlock Name="txtbl k" 

Text="Rotated Text" 

FontSize="48" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Top"> 
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<TextBlock.RenderTransform> 

<RotateTransform x:Name=" rotate" /> 
</TextBlock.RenderTransform> 
</TextBlock> 

</Grid> 


<Page.Triggers> 

<EventT rigger> 

<BeginStoryboard> 

<Storyboard RepeatBehavior="Forever"> 

<DoubleAnimation Storyboard.TargetName=" rotate" 

Storyboard.TargetPrope rty=" Angle" 
From= M 0" To="360" Durati on="0 :0:2" /> 

</Storyboard> 

</BeginStoryboard> 

</EventTrigger> 

</Page.Triggers> 

</Page> 


Without any additional code, this program would rotate the TextBlock around its upper-left corner, 
and it would sweep right off the screen at certain times during the animation. But the constructor 
of the code-behind file defines two event handlers to set the CenterX and CenterY properties of the 
RotateTronsform: 


Project: RotateAroundCenter I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

public MainPageO 

{ 

this. Initi alizeComponent(); 

Loaded += (sender, args)=> 

{ 

rotate.CenterX = txtblk.ActualWidth / 2; 

}； 

SizeChanged += (sender, args)=> 

{ 

rotate.CenterY = args.NewSize.Height / 2; 

}； 
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The center of rotation is set to a point aligned with the horizontal center of the TextBlock but a 
distance below the TextBlock equal to half the height of the page. The result is that the TextBlock 
rotates in a circle around the page center: 



Visual Feedback 


An animated transform can be effective for alerting the user to something on the screen that requires 
attention or for confirming that an operation has been initiated. In the JiggleButtonDemo program, 

I added a new User Control item that I named JiggleButton, but then I changed the base class in the 
XAML and C# files from User Control to Button. Here’s the complete JiggleButton.xaml file: 

Project: JiggleButtonDemo | JiggleButton.xaml 
<Button 

x:Cl ass="Ji ggleButtonDemo.JiggleButton" 

xml ns="http: //schemas.microsoft.com/winfx/2006/xaml/presentati on" 
xml ns : x="http: //schemas.microsoft.com/winfx/2006/xaml" 

RenderTransformOrigi n="0. 5 0.5" 

Cli ck="0n]i ggleButtonClick"> 


<Button.Resources 〉 

<Storyboard x: Key=" jiggleAnimation"> 

<DoubleAnimation Storyboard.TargetName=" rotate" 

Storyboard.TargetProperty=" Angle" 
From="0" To="10" Durati on="0 :0:0.33" 
AutoReverse="True"> 

<DoubleAnimation.EasingFunction> 

<ElasticEase Easi ngMode="EaseIn" /> 

</DoubleAnimation.EasingFunction> 

</DoubleAnimation> 

</Storyboard> 

</Button.Resources 〉 
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<Button.RenderTransform> 

<RotateTransform x:Name=" rotate" /> 
〈 /Button■RenderTransform> 

</Button> 


The content of the Button isn’t defined in this XAML file but three Button properties are set: 
RenderTronsformOrigin (in the root tag), Resources, and RenderTronsform. Normally, if you wanted to 
jiggle an element with a rotation, you'd need to use key frames because you first want to rotate from 
0 to 10 degrees (for example), then from 10 degrees to -10 degrees several times, and then back to 
0 degrees. But ElosticEose with an EosingMode of Eoseln is a great alternative. The DoubleAnimotion 
is defined to rotate the button 10 degrees and then back to zero, but the ElasticEose function 
incorporates wide negative swing, so the animation actually ranges from -10 to 10 degrees. 

The code-behind file for the JiggleButton simply triggers the animation in a Click event handler: 

Project: JiggleButtonDemo | JiggleButton.xaml.es 

using Windows.UI.Xaml; 

using Windows.UI.Xaml.Controls; 

using Windows.UI.Xaml.Media.Animation; 

namespace JiggleButtonDemo 
{ 

public sealed partial class DiggleButton : Button 
{ 

public JiggleButton() 

{ 

this .InitializeComponent(); 

} 

void OnJiggleButtonCli ck(object sender, RoutedEventArgs args) 

{ 

(this .Resources["ji ggleAnimation"] as Storyboard) .Begin(); 

} 



The MainPage.xaml file instantiates a JiggleButton so that you can play with it: 


Project: JiggleButtonDemo | File: MainPage.xaml (excerpt) 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<local : JiggleButton Content="Ji ggleButton Demo" 

FontSize="24" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Center" /> 

</Grid> 


Keep in mind that JiggleButton derives from Button, so you can use it just like any other Button, 
except that you shouldn't set the RenderTronsform or RenderTronsform Origin properties on it because 
doing so would interfere with the jiggle animation. 
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Translation 


TranslateTransform defines two properties X and / that cause an element to be rendered offset 
to its original position. One simple application of the TronslateTronsform is to display text with an 
"embossed" or "engraved” appearance, or with a drop shadow like this: 



Because light normally comes from above — and perhaps also because we’re accustomed to the con¬ 
vention that 3D-ish objects on the computer screen are illuminated with a light source from the upper 
left — the text on the top appears as if it has shadows at the right and bottom, and hence the letters 
are projecting outward from the screen. The engraved effect is opposite that: The shadows are on the 
left and top, and so the letters appear to be carved out. 

The page that displays those three text strings actually consists of six TextBlock elements. In the 
first two pairs, a TextBlock colored with the default foreground brush is covered by another TextBlock 
colored with the default background brush but offset by 2 pixels in the horizontal and vertical 
directions: 


Project: TextEffects | File: MainPage.xaml (excerpt) 

<Page … > 

<Page.Resources 〉 

〈Style TargetType="TextBlock"> 

〈Setter Property="FontFami ly" Val ue="Times New Roman" /> 
〈Setter Property="FontSize" Value="192" /> 

〈Setter Property="Hori zontalA1ignment" Val ue="Center" /> 
〈Setter Property="Verti calA1ignment" Val ue="Center" /> 
</Style> 

</Page.Resources 〉 
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<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Grid.RowDefinitions> 


<RowDefinition Height="*" /> 
<RowDefinition Height:"*" /> 
〈RowDefinition Height="*" /> 
</Grid.RowDefi ni ti ons> 


〈TextBlock Text="EMBOSS" 

Grid.Row= M 0" /> 

〈TextBlock Text=" EMBOSS" 

Grid.Row="0" 

Foreground="{StaticResource ApplicationPageBackgroundThemeBrush}"> 
<TextBlock.RenderTransform> 

<TranslateTransform X="-2" Y="-2" /> 

</TextBlock.RenderTransform> 

</TextBlock> 


<TextBlock Text=" ENGRAVE" 

Grid.Row= ,, l" /> 

<TextBlock Text=" ENGRAVE" 

Grid.Row= ,, l" 

Foreground="{StaticResource ApplicationPageBackgroundThemeBrush}"> 
<TextBlock.RenderTransform> 

<T ranslateT ransform X="2" Y="2" /> 

</TextBlock.RenderTransform> 

</TextBlock> 

<TextBlock Text="Drop Shadow" 

Grid.Row= ,, 2" 

Foreground="Gray"> 

<TextBlock.RenderTransform> 

<T ranslateT ransform X="6" Y="6" /> 

</TextBlock.RenderTransform> 

</TextBlock> 

<TextBlock Text="Drop Shadow" 

Grid.Row= ,, 2" /> 

</Grid> 

</Page> 


Notice that the embossing effect requires negative offsets (so that the TextBlock on top is shifted to 
the left and up) whereas the engraving effect has positive offsets. You can use these same effects just 
slightly less successfully with a dark theme, but you’ll have to switch the signs of the X and Y values. 

A drop-shadow effect is similar except that the text on top is colored normally and a gray shadow 
is offset underneath. 
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I don’t recommend using the following technique on a regular basis, but you can give your 
on-screen text a little bit of depth — that’s visual depth and not intellectual depth, alas — using a bunch 
of TextBlock elements offset from each other by one pixel: 



The generation of these elements is handled entirely in the code-behind file: 

Project: DepthText | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

const int COUNT =48; // 〜 1/2 inch 

public MainPage() 


this. InitializeComponent(); 

Grid grid = this .Content as Grid; 

Brush foreground = this .Resources ["ApplicationForegroundThemeBrush"] as Brush ; 
Brush grayBrush = new SolidColorBrush(Colors.Gray) ; 

for (int i = 0; i < COUNT; i++) 

{ 

bool firstOrLast = i == 0 || i == COUNT - 1; 

TextBlock txtblk = new TextBlock 

{ 

Text = "DEPTH", 

FontSize = 192 ， 

FontWeight = FontWeights .Bold, 

HorizontalAlignment = HorizontalA1ignment .Center, 
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Ve rticalA1ignment = VerticalA1ignment. Cente r, 
RenderTransform = new TranslateTransform 


X = COUNT - i - 1, 

Y = i - COUNT + 1, 

}, 

Foreground = firstOrLast ? foreground : grayBrush 

}； 

grid.Children.Add(txtblk); 



A TronsloteTronsform is a great way to move something a little bit from the position determined 
by the layout system. You’ll see a couple examples of TronsloteTronsform used in this way in the 
StandardStyles.xaml file. 

In Chapter 9 I showed an example of animating Canvas left and Canvas .Top attached properties 
to move an object around the screen. You can do the same type of animation by defining a 
TronsloteTronsform on the element you wish to move and using the animation to target the X and 
Y properties. One advantage is that the element being animated need not be a child of a Canvas, 
but there doesn’t seem to be a performance difference. Both types of animations are performed in 
secondary threads. 

Transform Groups 

I mentioned earlier that there are three ways to set a center of rotation but I was going to save the 
first way for a later discussion. Now is the time. It’s a little more complicated because it involves a 
transform that is constructed from other transforms. 

One of the classes that derives from Transform is TransformGroup, which has a property named 
Children of type TransformCollection, which you can use to construct a composite transform from 
multiple Transform derivatives. 

You might define a RototeTronsform like this: 

<RotateTransform Angl e="A" CenterX="CX" CenterY="CY" /> 

where A, CX, and CY are actual numbers or perhaps data bindings. That transform is equivalent to the 
following Transform Group: 


<TransformGroup> 

〈TranslateTransform X="-CX" Y="-CY" /> 
<RotateTransform Angle="A" /> 

〈TranslateTransform X="CX" Y="CY" /> 
</TransformGroup> 
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The two TransloteTransform tags seem to cancel each other out, but they surround a RototeTronsform. 
Let me demonstrate in two ways that this transform group is equivalent to the first RototeTronsform 
by itself. 

The following ImageRotate program references a bitmap on my website that I know is 320 pixels 
wide and 400 pixels tall. To rotate that bitmap around its center the RotateTransform would nor¬ 
mally have CenterX and CenterY set to half those values (160 and 200), but I’ve instead used a pair of 
TransloteTransform objects: 


Project: ImageRotate I File: MainPage.xaml (excerpt) 

<Page … > 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Image Sou rce="http: //www.charlespetzold.com/pw6/PetzoldJersey.jpg" 
Stretch="None" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Center"> 

<Image.RenderTransform> 

<T ransformGroup> 

<TranslateTransform X="-160" Y="-200" /> 

<RotateTransform x:Name=" rotate" /> 

<T ranslateT ransform X="160" Y="200" /> 

</TransformGroup> 

</Image.RenderTransform> 

</Image> 

</Gri d> 


<Page.Triggers> 

<EventTrigger> 

<Begi nStoryboard> 

<Storyboard Repeat Behavior="Forever"> 

<DoubleAnimation Storyboard.TargetName=" rotate" 

Storyboard.TargetPrope rty="Angle" 
From="0" To="360" Duration="0:0: B"> 
<DoubleAnimation.EasingFunction> 

<E1asticEase Easi ngMode="EaseInOut" /> 
</DoubleAnimation.EasingFunction> 

</DoubleAnimation> 

</Storyboard> 

</BeginStoryboard> 

</EventTrigger> 

</Page.Triggers> 

</Page> 
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The Elastic Ease animation with a mode of EaselnOut causes the image to rock back and forth crazily 
before and after it actually spins around, but you can see that the rotation is clearly around the 
image’s center: 



The following screenshot shows the process in the individual steps: The lightest Text Block 
is positioned in the center of the page. The next darkest TextBlock shows the effect of a 
TronsloteTransform that shifts the TextBlock left by half its width and up by half its height. The next 
darkest TextBlock is rotated relative to its origin — the upper-left corner of the original TextBlock. 
The final black TextBlock is then shifted by half its width and height. The final result is the original 
TextBlock rotated around its center: 
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Here’s the XAML file that created that image: 


Project: RotationCenterDemo I File: MainPage.xaml (excerpt) 

<Page … > 

<Page.Resources 〉 

<Style TargetType="TextBlock"> 

〈Setter Property="Text" Val ue="Rotate around Center" /> 
〈Setter Property="FontSi ze" Value="48" /> 

〈Setter Property="Hori zontalA1ignment" Val ue="Center" /> 
〈Setter Property="Verti calA1ignment" Val ue="Center" /> 
</Style> 

</Page.Resources 〉 


<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<TextBlock Name="txtbl k" 

Foreground="#D0D0D0" /> 

<TextBlock Foreground="#A0A0A0"> 

<TextBlock.RenderTransform> 

<T ranslateTransform x : Name="transl ateBackl" /> 

</TextBlock.RenderTransform> 

</TextBlock> 


〈TextBlock Foreground="#707070"> 

<TextBlock.RenderTransform> 

<T ransformGroup> 

<T ranslateT ransform x : Name="t ranslateBack2" /> 
<RotateTransform Angle="45" /> 

</TransformGroup> 

</TextBlock.RenderTransform 〉 

</TextBlock> 


<TextBlock Foreground="{Stati cResource ApplicationForegroundThemeBrush}"> 
<TextBlock.RenderTransform> 

<TransformGroup> 

<T ranslateT ransform x: Name="translateBack3" /> 

<RotateTransform Angle="45" /> 

<T ranslateT ransform x : Name="t ranslate" /> 

</TransformGroup> 

</TextBlock.RenderTransform 〉 

</TextBlock> 

</Gri d> 

</Page> 


The X and Y values for all the TranslateTransform tags are set from the Loaded handler: 


Project: RotationCenterDemo I File: MainPage.xaml.es (excerpt) 

public MainPage() 

{ 

this. InitializeComponentC); 


Loaded += (sender, args)=> 

{ 


translateBackl.X = 
translateBack2.X = 

translateBack3.X = -(translate.X = txtblk.ActualWidth / 2); 
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translateBackl.Y = 
translateBack2.Y = 

translateBack3.Y = -(translate.Y = txtblk.Actual Height / 2); 

}； 

} 


Transforms can be combined for some very interesting effects that might initially seem beyond 
the scope of the nonmathematical, nongraphics programmer. Here’s a XAML file that uses a Polygon 
element to define a simple propeller shape, and then applies three transforms to it, a RotateTransform, 
a TronsloteTransform, and another RototeTronsform: 


Project: Propeller I File: MainPage.xaml (excerpt) 

<Page … > 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
〈Polygon Poi nts="40 0, 60 0, 53 47, 

100 40, 100 60, 53 53, 

60 100, 40 100, 47 53, 

0 60, 0 40, 47 47" 

Stroke="{StaticResource ApplicationForegroundThemeBrush}" 
Fill="SteelBlue" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Center" 

RenderTransform0rigin="0. 5 0.5"> 

<Polygon.RenderTransform> 

<T ransformGroup> 

<RotateTransform x:Name="rotatel" /> 

<TranslateTransform X="300" /> 

<RotateTransform x:Name="rotate2" /> 

</TransformGroup> 

〈 /Polygon■RenderT ransform> 

</Polygon> 

</Gri d> 


<Page.Triggers> 

<EventT rigger> 

<BeginStoryboard> 

<Storyboard> 

<DoubleAnimation Storyboard .TargetName="rotatel" 

Storyboard.TargetPrope rty="Angle" 
From= M 0 n To=__360 n Duration="0:0:0. 5 
RepeatBehavior=" Forever" /> 


<DoubleAnimation Storyboard .TargetName="rotate2" 

Storyboard.TargetPrope rty="Angle" 
From="0" To="360" Durati on="0 :0:6" 


</Storyboard> 
</BeginStoryboard> 
</EventTrigger> 
</Page.Triggers> 

</Page> 


RepeatBehavior=" Forever" /> 
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The Storyboard contains two DoubleAnimation objects. The first DoubleAnimation targets the first 
RotateTransform object to rotate the propeller itself around its center at the speed of 2 cycles per 
second. The TronsloteTronsform moves this rotating propeller 300 pixels to the right of the center of 
the page, and the second DoubleAnimation targets the second RotateTransform to rotate the pro¬ 
peller again. But this rotation is relative to the original center of the propeller, which means that the 
propeller circles the center of the page with a radius of 300 pixels at the rate of 10 revolutions per 
minute. 



Now it’s perhaps clear how RenderTronsformOrigin works: RenderTronsformOrigin is equivalent to 
performing a TranslateTronsform with negative X and Y values prior to the transform specified as the 
RenderTransform property, and performing another TranslateTronsform with positive X and Y values 
after the RenderTronsform. 


The Scale Transform 


The ScoleTransform class defines properties named ScoleX and ScoleY that increase or decrease the 
size of an element independently in the horizontal and vertical directions. If you want to preserve 
the correct aspect ratio of a target, you’ll need to use the same values for ScoleX and ScoleY. If it’s an 
animation, you need two animation objects. 

The ScoleTransform does not affect the Actual Width and ActualHeight properties of an element. 
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You’ve seen how to use a Viewbox to stretch a Text Block in ways that violate its typographically 
correct aspect ratio. Here's how to do it with a ScaleTronsform: 


Project: OppositelyScaledText I File: MainPage.xaml (excerpt) 

<Page … > 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<TextBlock Text="Scal ed Text" 

FontSi ze="144" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Center" 

RenderTransformOrigi n="0.5 0.5"> 

<TextBlock.RenderTransform> 

<ScaleTransform x:Name="scale" /> 

</TextBlock.RenderTransform> 

</TextBlock> 

</Gri d> 


<Page.Triggers> 

<EventT rigger> 

<BeginStoryboard> 

<Storyboard> 

<DoubleAnimation Storyboard .TargetName="scal e" 

Storyboard.TargetPrope rty=" SealeX" 

Begi nTime="0:0: 2" 

From="l" To="0.01" Durati on="0 :0:2" 

AutoReverse="T rue" 

RepeatBehavior=" Forever" /> 

<DoubleAnimation Storyboard .TargetName="scale" 

Storyboard.TargetPrope rty=" SealeY" 

From="10" To="0.1" Duration="0:0: 2" 

AutoReverse="T rue" 

RepeatBehavior=" Forever" /> 

</Storyboard> 

</BeginStoryboard> 

</EventTri gger> 

</Page.Triggers> 

</Page> 

This is actually not quite the way I wanted to write this program. I originally gave the Text Block a 
Font Size of 1 and then animated ScaleX from 1 to 144 and ScoleY from 144 to 1, both reversed and 
repeated forever. That should probably have worked, but it resulted in the 1-pixel-high font being 
increased in size by a factor of 144 rather than becoming a 144-pixel-high font. To get the program 
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to work in a way I wanted, I gave the TextBlock a 144-pixel size and started the animations offset from 
each other. The TextBlock alternately stretches out horizontally and vertically: 



Scaling is like rotation in that it is always in reference to a center point. The ScoleTransform 
class defines CenterX and CenterY properties just like RototeTronsform, or you can set 
RenderTronsformOrigin as I’ve done in the OppositelyScoledText program. The scaling center is the 
point that remains in the same location when the scaling occurs. 

Scaling and rotation centers play a big role in manipulating on-screen objects (such as 
photographs) with your fingers. As you stretch, pinch, and rotate a photograph, the scaling and 
rotation centers change as your fingers move relative to each other. Ill discuss the technique for 
calculating these rotation centers in Chapter 13. 


Negative scaling factors flip an element around the horizontal or vertical axis. This technique is 
particularly useful for creating reflection effects. Unfortunately, the Windows Runtime is missing an 
important contributor to this effect: a UlElement property named OpacityMask of type Brush that 
allows defining a graduated opacity based on the alpha channel of the colors of a gradient brush. In 
the Windows Runtime, you’ll have to mimic a graduated fade-out by covering up the element with 
another element that has a gradient brush incorporating transparency and the background color. 


This is demonstrated in the ReflectedFadeOutlmage project. The upper half of a Grid is shared 
by two items: an Image and another Grid. That second Grid contains the same Image covered by a 
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Rectangle with a LinearGradientBrush that fades from the background color at top to transparent at 
the bottom: 


Project: ReflectedFadeOutlmage I File: MainPage.xaml (excerpt) 

<Page … > 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

<Grid.RowDefinitions> 

<RowDefinition Height:"*" /> 

〈RowDefinition Height="*" /> 

</Grid.RowDefi ni ti ons> 

<Image Sou rce="http: //www.charlespetzold.com/pw6/PetzoldJersey.jpg" 

HorizontalAli gnment="Center" /> 

<Grid RenderTransformOrigi n="0 1" 

HorizontalAli gnment="Center"> 

<Grid.RenderTransform> 

<ScaleTransform ScaleY="-l" /> 

</Grid.RenderTransform> 

<Image Source="http: //www.charlespetzold.com/pw6/PetzoldDersey.jpg" /> 

<Rectangle> 

〈 Rectangle.Fi11 > 

<LinearGradientBrush StartPoi nt="0 0" EndPoint="0 1" > 

<GradientStop 0ffset="0" 

Color="{Bi nding 

Source={Stati cResource ApplicationPageBackgroundThemeBrush} , 
Path=Color}" /> 

<GradientStop Offset="l" Color="Transparent" /> 

</LinearGradientBrush> 

</Rectangle.Fi11> 

</Rectangle> 

</Grid> 

</Gri d> 

</Page> 


CHAPTER 10 Transforms 


399 


That inner Grid is also reflected around its bottom edge. The RenderTransformOrigin assigns a 
transform center at the lower left, and the ScaleTronsform sets ScoleY to -1, which flips the element 
around the horizontal axis: 



In Chapter 14, "Bitmaps,” I’ll demonstrate another way to achieve this effect accessing the pixels of 
a bitmap and setting the transparency appropriately. 


Building an Analog Clock 


An analog clock is round. This simple fact implies that drawing the clock would probably be 
mathematically easiest if you use arbitrary coordinates — that is, coordinates not in units of pixels 
but in units you choose for convenience — with the origin in the center. Putting the origin in the 
center also means you probably won’t need to mess around with CenterX or CenterY settings for the 
RototeTronsform objects that position the hands of the clock because the origin is also the center of 
rotation. 

The traditional analog clock in a graphical environment adapts itself to whatever size it’s given. 

It is tempting to use a Viewbox for this job, but with an analog clock that could be a problem. The 
layout system (and Viewbox) perceives the size of a vector graphics object to be the maximum X and 
Y values of its coordinate points. Negative coordinates are ignored, including those in three-quarters 
of an analog clock with an origin in the center. 
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The layout system (and Viewbox) will not correctly determine the size of graphics objects with 
negative coordinates, and a little "help" is required. Fortunately, transforms cascade from parent to 
child. You can set a transform on a Grid, and it will apply to everything in that Grid. The contents of 
the Grid can then have their own transforms. 

That’s what I’ve done in the AnalogClock program. All the graphics are in a Grid that is fixed in size 
with a 200-pixel Width and Height implying a 100-pixel radius: 

〈Grid Width="200" Hei ght="200"> 

… clock graphics go here 

</Grid> 

Within that Grid are five Path elements that render the tick marks around the circumference of 
the clock, as well as the hour, minute, and second hands. These are all based on a coordinate system 
with X and Y values ranging from -100 to 100. If you could see that Grid (outlined here in red) and the 
clock, it would look like this: 



The Grid is positioned in the center of the page thanks to its default alignment, but the center of 
the clock is positioned at the upper-left corner of the Grid because that’s where the point (0, 0) is. 

Now let's put that Grid in a Viewbox, like so: 

<Viewbox> 

〈Grid Width= M 200" Hei ght="200"> 

… clock graphics go here 

</Grid> 

</Viewbox> 
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The Viewbox can correctly handle elements that have an origin at the upper-left corner but not 
graphics with negative coordinates: 



Fortunately, the fix is fairly easy. All that’s necessary is to shift the Grid and the clock. This 
transform occurs before the Viewbox gets ahold of the element, so it’s merely by 100 pixels: 

<Viewbox> 

〈Grid Width="200" Hei ght="200"> 

<Grid.RenderTransform> 

<T ranslateTransform X="100" Y="100" /> 

</Grid.RenderTransform> 

… clock graphics go here 

</Gri d> 

</Viewbox> 
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And here it is: 



Now all that's needed is to get rid of that red border. 

The clock consists of five Path elements. Each of the three hands is defined by path markup syntax 
consisting of straight lines and Bezier curves. Here’s the hour hand pointing to the 12:00 position. 
Because the hand is initially mostly on the top half of this clock, most of the hand has negative Y 
coordinates with only a few positive Y coordinates as it loops around the center. 

〈Path Data="M 0 -60 C 0 -30, 20 -30, 5 -20 L 5 0 

C 5 7.5, -5 7.5, -5 0 L -5 -20 
C -20 -30, 0 -30, 0 -60"> 

<Path.RenderTransform> 

<RotateTransform x : Name=" rotateHour" /> 

</Path.RenderTransform> 

</Path> 


The tick marks are actually dotted lines. Here’s the Path element for the small tick marks: 

<Path Fill="{x:Null}" 

StrokeThi ckness="3" 

StrokeDashArray="0 3.14159"> 

<Path.Data 〉 

<E11ipseGeometry Radi usX="90" RadiusY="90" /> 

〈 /Path.Data 〉 

</Path> 

This creates a circle with a radius of 90, so the circumference is 2n90, which means that the 60 tick 
marks are separated by 3 ti, which not coincidentally is the product of the StrokeThickness and number 
in the StrokeDashArroy indicating the distance between the dots in units of the StrokeThickness. 
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Since you enjoyed that one, here’s the Path for the large tick marks: 


<Path Fin="{x:Null}" 

StrokeThi ckness="6" 

StrokeDashArray="0 7.854"> 

<Path.Data 〉 

<E11ipseGeometry Radi usX="90" RadiusY="90" /> 
〈 /Path.Data 〉 

</Path> 


Again, the circumference is 2ti90, but there are only 12 tick marks, so they are separated by 15ti 
which is close enough to the product of 6 and 7.854. Here’s everything put together: 


Project: AnalogClock I File: MainPage.xaml (excerpt) 

<Page … > 


<Page.Resources 〉 

〈Style TargetType="Path"> 

〈Setter Prope rty=" Stroke" 

Val ue="{StaticResource ApplicationForegroundThemeBrush}" /> 
〈Setter Property="StrokeThi ckness" Value="2" /> 

〈Setter Property="StrokeStartLi neCap" Val ue="Round" /> 

〈Setter Property="StrokeEndLi neCap" Val ue="Round" /> 

〈Setter Property="StrokeLi neHoin" Val ue="Round" /> 

〈Setter Property="StrokeDashCap" Val ue="Round" /> 

〈Setter Property="Fi 11" Value="Blue" /> 

</Style> 

</Page.Resources 〉 


<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

<Viewbox> 

<!-- Grid containing all graphics based on (0, 0) origin, 100-pixel radius --> 
<Grid Width="200" Height="200"> 

<!-- Transform for entire clock --> 

<Grid.RenderTransform> 

<TranslateTransform X="100" Y="100" /> 

</Grid.RenderTransform> 

<!-- Small tick marks --> 

<Path Fill="{x:Nun}" 

StrokeThi ckness="3" 

StrokeDashArray="0 3. 14159% 

<Path.Data> 

<E11ipseGeometry Radi usX="90" Radi usY="90" /> 

〈/Path _ Data 〉 

</Path> 

<!-- Large tick marks --> 

<Path Fill="{x:Null} M 

StrokeThi ckness="6" 

StrokeDashArray="0 7.854"> 

<Path.Data> 

<E11ipseGeometry Radi usX="90" Radi usY="90" /> 

〈/Path _ Data 〉 

</Path> 
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<!-- Hour hand pointing straight up --> 

〈Path Data="M 0 -60 C 0 -30, 20 -30, 5 -20 L 5 0 

C 5 7.5, -5 7.5, -5 0 L -5 -20 

C -20 -30, 0 -30, 0 -60"> 

<Path.RenderTransform> 

<RotateTransform x : Name=" rotateHour" /> 

</Path.RenderTransform> 

</Path> 

<!-- Minute hand pointing straight up --> 

〈Path Data="M 0 -80 C 0 -75, 0 -70, 2.5 -60 L 2.5 0 

C 2.5 5, -2.5 5, -2.5 0 L -2.55 -60 

CO -70, 0 -75, 0 -80"> 

<Path.RenderTransform> 

<RotateTransform x : Name=" rotateMinute" /> 

</Path.RenderTransform> 

</Path> 


<!-- Second hand pointing straight up --> 

<Path Data="M 0 10 L 0 -80"> 

<Path.RenderTransform> 

<RotateTransform x : Name=" rotateSecond" /> 
</Path.RenderTransform> 

</Path> 

</Grid> 

</Viewbox> 

</Gri d> 

</Page> 


The code-behind file is responsible for calculating angles measured clockwise from 12:00 for the 
three RototeTronsform objects: 

Project: AnalogClock I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

public MainPageO 

{ 

this. Ini ti alizeComponent(); 

CompositionTarget .Rendering += OnCompositionTargetRendering; 

} 


void OnCompositionTargetRendering (object sender, object args) 

DateTime dt = DateTime. Now; 

rotateSecond.Angle = 6 * (dt■Second + dt.Mi 11 isecond / 1000.0); 
rotateMinute.Angle = 6 * dt.Minute + rotateSecond.Angle / 60; 
rotateHour.Angle = 30 * (dt.Hour % 12) + rotateMinute.Angle / 12; 



This clock has a "sweep" second hand that seems to move continuously. If you prefer a 
"tick” second hand that jumps by seconds, you can simply remove the milliseconds from the 
calculation. But a better solution is using a DispotcherTimer with an interval of 1 second rather than 
CompositionTorget.Rendering, which always goes at the video refresh rate. 
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Skew 


I discussed earlier that all the classes that derive from Transform are restricted to defining two- 
dimensional affine transforms, and one of the characteristics of an affine transform is the preservation 
of parallel lines. However, an affine transform does not necessarily preserve angles between lines. For 
example, an affine transform is capable of transforming a square to a parallelogram: 



In the Windows Runtime, this type of transform is known as a skew, but in other graphics 
environments it might be called a shear. The figure is progressively shifted positively or negatively in 
the horizontal or vertical direction. In a sense, the skew is the most extreme of the affine transforms, 
but it still preserves a great deal of the original geometry. A skew transform applied to a circle or 
ellipse never results in anything other than an ellipse: 



Similarly, a skewed Bezier curve remains a Bezier curve. 

The SkewTronsform has AngleX and AngleY properties that you set to an angle in degrees. The 
examples shown were created with a SkewTransform with AngleX set to 45 degrees, which skews 
the bottom to the right. Set the angle negative to skew the bottom to the left. For text, negative 
AngleX values create an oblique effect (similar to italic but without any typographical changes to the 
characters). Here’s AngleX set to -30 degrees: 
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Nonzero settings oi AngleY cause skew in the vertical direction. Positive values of AngleY cause the 
right side of figures to skew down: 



Negative values cause the right sides to skew up. By default, the upper-left corner of the figure stays 
in the same location with the skew, but you can change that with CenterX and CenterY properties or 
with RenderTransformOrigin. 

The following program demonstrates what happens when you combine AngleX and AngleY 
skewing: 


Project: SkewPlusSkew | File: MainPage.xaml (excerpt) 

<Page … > 

<Grid Background="{StaticResource ApplicationPageBackgroundThemeBrush}"> 

〈TextBlock Text="SKEW" 

FontSize="288" 

FontWei ght="Bol d" 

HorizontalAli gnment="Center" 

VerticalAl ignment="Center" 

RenderTransformOrigi n="0.5 0.5"> 

<TextBlock.RenderTransform> 

<SkewTransform x:Name="skew" /> 

</TextBlock.RenderTransform> 

</TextBlock> 

</Grid> 

<Page.Triggers> 

<EventT rigger> 

<BeginStoryboard> 

<Storyboard SpeedRatio="0. 5" RepeatBehavior="Forever"> 

<DoubleAnimationUsingKeyFrames Storyboard .TargetName="skew" 

Storyboard.TargetPrope rty="Angl eX"> 


<! 




Back and forth for 4 seconds --> 


<DiscreteDoubleKeyFrame KeyTime="0:0:0" Value="0" /> 
<LinearDoubleKeyFrame KeyTime="0:0:l" Value="90" /> 
<LinearDoubleKeyFrame KeyTime="0:0:2" Value="0" /> 
<LinearDoubleKeyFrame KeyTime="0:0: 3" Value="-90" /> 
<LinearDoubleKeyFrame KeyTime="0:0:4" Value="0" /> 
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<!-- Do nothing for 4 seconds --> 

<DiscreteDoubleKeyFrame KeyTime="0:0: 8" Value="0" /> 


<!-- Back and forth for 4 seconds --> 

<LinearDoubleKeyFrame KeyTime="0:0:9" Value="90" /> 

<LinearDoubleKeyFrame KeyTime="0:0:10" Value="0" /> 

<LinearDoubleKeyFrame KeyTime="0:0:ll" Value="-90" /> 

<LinearDoubleKeyFrame KeyTime="0:0:12" Value="0" /> 

</Doubl eAni mati onllsi ngKeyFrames> 

<Doubl eAni mati onllsi ngKeyFrames Storyboard .TargetName="skew" 

Storyboard.TargetPrope rty="Angl eY"> 

<!-- Do nothing for 4 seconds --> 

<DiscreteDoubleKeyFrame KeyTime="0:0:0" Value="0" /> 

<DiscreteDoubleKeyFrame KeyTime="0:0:4" Value="0" /> 


<!-- Back and forth for 4 seconds --> 
<LinearDoubleKeyFrame KeyTime="0:0: 5" 
<LinearDoubleKeyFrame KeyTi me="0 :0:6" 
<LinearDoubleKeyFrame KeyTi me="0 :0:7" 
<LinearDoubleKeyFrame KeyTi me="0 :0:8" 


Value= M -90" /> 
Value="0" /> 
Value="90" /> 
Value="0" /> 


<!-- Back and forth for 4 seconds --> 

<LinearDoubleKeyFrame KeyTime="0:0:9" Value="-90" /> 
<LinearDoubleKeyFrame KeyTime="0:0:10" Value="0" /> 
<LinearDoubleKeyFrame KeyTime="0:0:ll" Value="90" /> 
<LinearDoubleKeyFrame KeyTime="0:0:12" Value="0" /> 
</Doubl eAni mati onllsi ngKeyFrames> 

</Storyboard> 

</BeginStoryboard> 

</EventTrigger> 

</Page.Triggers> 

</Page> 


I’ve set the Speed Ratio on the Storyboard to 0.5 so that you can better relish the effects, but I’ll use 
the key frame times to discuss what’s going on. During the first four seconds, the first animation ani¬ 
mates the AngleX property to 90 degrees, back to zero, to -90 degrees, and back to zero. During the 
next four seconds the second animation animates the AngleY property between -90 and 90. During 
the final four seconds, the two animations go together. 
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You may or may not be surprised that combining AngleX and AngleY in this way results in rotation: 



However, as a result of the mathematics, the figure gets larger as well. 


Skew is often used to give a little 3D-like depth to elements, but it works best in combination with 
an unskewed element, as I’ll demonstrate later in this chapter. 


Making an Entrance 


Sometimes you want an animated transform to occur on an element when a page is first loaded. For 
example, an element might slide in from the side and then come to rest, or expand in size, or spin in 
from above. 

It's generally easiest to begin by positioning the element in its final location with no transforms. 
You can then define the transforms and animations so that the element ends up in that spot. Often 
you can simply leave out the To value of a DoubleAnimotion on a transform because the To value is 
the same as the pre-animation default value. 

This is demonstrated in the SkewSlidelnText project. As you can see, the Text Block has some 
transforms defined, but with default values the element simply sits in the center of the display. That's 
the final location and orientation of the TextBlock, and the animations conclude at that spot. 


Project: SkewSlidelnText | File: MainPage.xaml (excerpt) 

<Page … > 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
〈TextBlock Text="Hello! " 

FontSize= n 192" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Center" 
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RenderTransformOrigi n="0. 5 1"> 

<TextBlock.RenderTransform> 

<T ransformGroup> 

<SkewTransform x:Name="skew" /> 

<TranslateTransform x : Name="t ranslate" /> 
</TransformGroup> 

</TextBlock.RenderTransform> 

</TextBlock> 

</Gri d> 


<Page.Triggers> 

<EventTrigger> 

<BeginStoryboard> 

<Storyboard> 

<DoubleAnimation Storyboard.TargetName=" translate" 

Storyboard.TargetProperty="X" 
From="-1000" Durati on="0 :0:1" /> 

<Doubl eAni mati onllsi ngKeyFrames 

Storyboard .TargetName="skew" 

Storyboard.TargetPrope rty="Angl eX"> 

<DiscreteDoubleKeyFrame KeyTime="0:0:0" Value="15" /> 
<LinearDoubleKeyFrame KeyTime="0:0:l" Value="30" /> 
<EasingDoubleKeyFrame KeyTime="0:0:l. 5" Val ue="0"> 
<EasingDoubleKeyFrame.EasingFunction> 

<ElasticEase /> 

</EasingDoubleKeyFrame.EasingFunction> 

</EasingDoubleKeyFrame> 

</Doubl eAni mati onllsi ngKeyFrames> 

</Storyboard> 

</BeginStoryboard> 

</EventTrigger> 

</Page.Triggers> 

</Page> 


The DoubleAnimation applied to the TranslateTronsform has a From value that starts the TextBlock 
1000 pixels to the left of its final location. The absence of a To value means that the animation ends at 
the pre-animation value, which is 0. 

As that’s happening, a DoubleAnimationilsingKeyFrames makes the skew progress from an AngleX 
value of 15 degrees to 30 degrees, as if the TextBlock is being pulled into the center of the screen. The 
final key frame then animates the AngleX back to its pre-animation value of 0, shaking it back and 
forth in the process. 


Transform Mathematics 


I stated at the outset of this chapter that a transform is a formula that converts a point (x, y) 
into {x\ y') and performs that conversion for all the points of an element. It’s now time to look at 
that math. 
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Suppose a TranslateTransform has its X and Y properties set to TX and TY. The transform formulas 
add these translation factors to x and y: 

x r = x + TX 
y =y + TY 

If the ScoleX and ScoleY properties of a ScaleTransform are set to SX and SY, the transform formulas 
are also fairly obvious: 

y = SY-y 

Now that we have the basics down, let’s start combining transforms, such as in a TronsformGroup. 

If the ScaleTransform occurs first, followed by the TranslateTransform, the formulas are: 

x r = SX-x + TX 
y = SY-y + TY 

But if the translate transform is applied first, followed by the scale transform, ifs a little different: 

x f = SX-(x + TX) 

/ = SY.(y + TY) 

The translation factors are now effectively multiplied by the scaling factors. 

The ScaleTransform defines ScoleX and ScoleY properties but also CenterX and CenterY. I discussed 
earlier how the center point is used to construct two translations. The first translation is negative, 
which is then followed by the scale or rotation, followed by positive translation. Suppose CenterX and 
CenterY are set to the values CX and CY. The composite scaling formulas are: 

x r = SX-(x-CX) + CX 

/ = SX-(y-CY) + CY 

You can easily confirm that the point (CX, CY) is transformed to the point (CX, CY), which is the 
characteristic of the center of scaling: the point that the transform leaves unchanged. 

In all the cases so far, has depended solely on constants multiplied by and added to x, and y' 
has depended only on constants multiplied by and added toy. With rotation, it gets a bit messier 
because x 7 depends on both x and y, and y' also depends on both x and y. If the Angle property of a 
RotateTronsform is set to A, the transform formulas are: 

x’ = cos(^4)« x-sin(^4) • y 

/ = sin ㈤. x + cos(j) 
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These formulas are pretty easy to confirm for simple cases. \i A is zero, the formulas are just: 

X’ = x 

/ = y 

IM is 90 degrees, the sine is 1, and the cosine is 0, so 
x r - -y 
y f = x 

For example, the point (1, 0) is transformed to (0, 1), and (0, 1) is transformed to (-1, 0). When A is 180 
degrees, the sine is 0 and the cosine is -1, so 

x f = -x 

y =-y 

It’s a reflection around the origin, and you can get the same effect with a ScoleTronsform with ScaleX 
and ScaleY both set to -1. When A is 270 degrees, 

x f = y 

y f = -x 

Here’s the first diagram of a skew transform shown earlier: 



The transform formulas for this particular skew (AngleX set to 45 degrees) are 

x f = x-\- y 

/ = y 

When y equals 0 (at the top of the figure), x 7 simply equals x and y' equals y. But as you move down 
the figure, y gets larger, so x' becomes increasing greater than 兄 The generalized formulas for 
SkewTransform when AngleX is set to AX and AngleY is set to AY are 

x f = x + sin^AX)* y 

y f =sin(^47)«x +j 

When you begin exploring combinations of rotation with other transforms, this type of notation 
starts to become rather clumsy. Fortunately, matrix algebra comes to the rescue. When individual 
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transforms are expressed as matrices, transforms can be combined through the well-established 
process of matrix multiplication. 

Let’s represent a point [x, y) as a 2x1 matrix: 

x y 

And let’s represent the transform as a 2x2 matrix: 

Mil M12 
M21 Mil 

Applying the transform can then be represented with a matrix multiplication. The result is the 
transformed point: 

Mil M12 

x y x 

M21 Mil 

The rules of matrix multiplication imply the following formulas: 
x r =MU-x + M2\-y 
>/=M12.x + M22.j ； 

This process works for scaling if Mil is the ScoleX value and M22 is the ScoleY value, and M21 and 
M12 are zero. It also works for rotation and skewing, which both involve factors that are multiplied by 
x and y. 

But it does not work for translation. The translation formulas look like this: 

= x + TX 
V = y + TY 

These translation factors are added in by themselves, not multiplied by x ory. How can we represent 
a generalized transform by a matrix if it doesn’t allow for translation, which is arguably the simplest 
type of transform of them all? 

The interesting solution is to introduce a third dimension. In addition to the X and Y axes on the 
plane of the computer screen, a conceptual Z axis extends out from the screen. Let’s assume that 
weYe still drawing on a two-dimensional plane, but that plane exists in 3D space with a constant Z 
coordinate equal to 1. 

This means that the point (x,y) is actually the point [x,y, 1) and we can represent it as a 3xl matrix: 

x y l 
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The matrix transform is now a 3x3 matrix, and the multiplication looks like this: 




Mil 

M12 

M13 


x y 1 

X 

M21 

M22 

M23 

— 

X’ y 〆 



M31 

M32 

M33 



The formulas implied by the matrix multiplication are: 
x ， =A/ll.x + M21 • 少 + M31 
/ =M12.x + M22 • 少 + M32 
z r =M\3-x + M23-y + M33 

This is a partial success because the transform formulas now include translation factors of M31 and 
M32. These two numbers aren’t multiplied by x ory. 

But it’s not a total success because z' is generally not equal to 1, which means that we’ve shifted off 
the plane where z always equals 1. One way to get back to that plane is simply to set all those errant 
z' values to 1. But shouldn’t points that are transformed a long distance away from the plane where z 
equals 1 be distinguished from those that end up close to it? 

One clever way to get the z values to 1 without simply ignoring them is to take the 3xl matrix 
result and divide all three coordinates by z ’： 


/ / / / \ 
x y z 、 


/ / / \ 
x 少 1) 

， f 



\Z Z Z J 


Z J 


This approach to representing two-dimensional transforms with three-dimensional coordinates 
is called homogenous coordinates, and it was developed by August Mobius in the 1820s as a way to 
represent infinity, which results when z' is zero. But for us, infinite coordinates are a problem. If we 
want to avoid infinite coordinates, z' cannot be allowed to be zero. Indeed, we can avoid dividing by 
z' entirely if we ensure that z' is always equal to 1. 

It’s possible to do that by setting M13 and M23 in the matrix to 0 and M33 to 1. Now the trans¬ 
form is represented by formulas that remain entirely in the same plane: 



Mil 

M12 

0 


X 少 l|x 

M21 

M22 

0 

— 

X ， / 1 


M31 

M32 

1 



This is the standard matrix representation of the two-dimensional affine transform. (Allowing other 
values in the third column results in a non-affine transform. Because such a matrix is capable of 
transforming parallel lines to nonparallel lines, it is sometimes also called a toper transform.) 
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With the notation I was using earlier, the ScaleTronsform where ScoleX is set to SX and ScaleY is set 
to SY is 


x y 


SX 0 0 

l|x 0 SY 0 = |x r / 1 

0 0 1 


A TronslateTronsform with TX and TY factors is 


% 少 


1 0 0 

l|x 0 1 0=|x， 〆 1 

TX TY 1 


A ScoleTransform with center {CX, CY) is effectively a multiplication of three 3x3 transforms: 




1 

0 

0 


SX 

0 

0 


1 

0 

0 


X ^ 1 

X 

0 

1 

0 

X 

0 

SY 

0 

X 

0 

1 

0 

— 

X ， 〆 1 



~CX 

-CY 

1 


0 

0 

1 


cx 

CY 

1 



Similarly, a RototeTronsform with angle A and center [CX, CY) also informs three transforms: 




1 

0 

0 


cos(j) 

sin( 3) 

0 


1 

0 

0 


x y \ 

X 

0 

1 

0 

X 

-sin(j) 

cos(J) 

0 

X 

0 

1 

0 

— 

X，〆 1 



~CX 

-CY 

1 


0 

0 

1 


CX 

CY 

1 



And here’s the SkewTransform with angles AX and AY and a center: 




1 

0 

0 


1 

sin(^47) 

0 


1 

0 

0 


x y 1 

X 

0 

1 

0 

X 

sin(A\") 

1 

0 

X 

0 

1 

0 

— 

x' 〆 1 



~CX 

-CY 

1 


0 

0 

1 


CX 

CY 

1 



A well-known property of matrix multiplication is that it is not commutative. The order of 
multiplication makes a difference. This has already been demonstrated with translation and scaling. If 
the translation comes first, the translation factors themselves are also scaled by the scaling factors. 


However, certain types of transforms can be safely multiplied in any order: 


■ Multiple TronslateTronsform objects. The total translation is the sum of the individual 
translation factors. 


■ Multiple ScoleTransform objects with the same scaling center. The total scaling is the product 
of the individual scaling factors. 

■ Multiple RotateTra ns forms with the same rotation center. The total rotation is the sum of the 
angles of the individual rotations. 
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In addition, if a ScaleTransform has equal ScaleX and ScoleY properties, it can be multiplied by a 
RototeTronsform or a SkewTronsform in either order. 


The Windows Runtime defines a Matrix structure that has six properties that correspond to the 
cells of the matrix like this: 

Mil M12 0 

M21 M22 0 

OffsetX OffsetY 1 

The last row of this matrix is fixed. You cannot use this Matrix structure to define a taper transform or 
anything "crazier” than what you’ve already seen. OffsetX and OffsetY are the translation properties. 
The default values for Mil and M22 are 1, and the default values for the other four properties are 
zero. That’s the identity matrix with a diagonal of Is: 

1 0 0 

0 1 0 

0 0 1 

The Matrix structure has a static Identity property that returns this value and an Isldentity property 
that returns true if the Matrix \/a\ue is the identity matrix. 

Along with the "easy" Transform derivatives like ScaleTransform and RotateTronsform, there is also 
the low-level alternative MotrixTronsform, which has a property of type Matrix. If you know the matrix 
transform you want, you can specify it directly in six numbers in the order Mil, M12, M21, M22, 
OffsetX, OffsetY. Here’s one way to set this transform: 

<TextBlock … > 

<TextBlock.RenderTransform> 

<MatrixTransform Matri x="10 0 0 5 0 100" /> 

</TextBlock.RenderTransform> 

〈 /TextBlock 〉 

This transform scales in the horizontal direction by a factor of 10 (Mil) and in the vertical direction by 
a factor of 5 (M22), and then it shifts the TextBlock down by 100 pixels [OffsetY). But you can also set 
the transform directly to the RenderTronsform property: 

<TextB"lock … 

RenderTransform="10 0050 100" 

... /> 

The preview design view in Microsoft Visual Studio doesn’t particularly care for this syntax, but it’s no 
problem for the compiler or Windows 8. 
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Using this implicit form of MatrixTransform is handy for several common rotation transforms that 
are shown in the following program. Each TextBlock displays the transform applied to it: 

Project: CommonMatrixTransforms I File: MainPage.xaml (excerpt) 

<Page … > 

<Page.Resources 〉 

<Style TargetType="TextBlock"> 

〈Setter Property="FontSi ze" Value="24" /> 

〈Setter Property="RenderTransformOri gin" Val ue="0 0.5" /> 

</Style> 

</Page.Resources> 


<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

<!-- Move origin to center --> 

<Canvas HorizontalA1i gnment="Center" 

VerticalAli gnment="Center"> 

〈TextBlock Text=" RenderTransform='1 00100'" 
RenderTransform="l 0 0 1 0 0" /> 

cTextBlock Text=" RenderTransform='.7 .7 -.7 .7 0 O'” 
RenderTransform=" .7 .7 -.7 .7 0 0" /> 

<TextBlock Text=" RenderTransform='0 1-1000'" 

RenderTransform="0 1 -1 0 0 0" /> 

〈TextBlock Text=" RenderTransform='-.7 .7 -.7 -.7 0 0" 
RenderTransform="- .7 .7 - .7 -.7 0 0" /> 

<TextBlock Text=" RenderTransform='-1 00-100'" 
RenderTransform="-l 00-10 0" /> 

cTextBlock Text=" RenderTransform=' - .7 - .7 .7 -.7 0 O'" 
RenderTransform="- .7 -.7 .7 -.7 0 0" /> 

<TextBlock Text=" RenderTransform='0 -1 1 0 0 O'" 

RenderTransform="0 -1 1 0 0 0" /> 

〈TextBlock Text=" RenderTransform='.7 -.7 .7 .7 0 0" 

RenderTransform=" .7 -.7 .7 .7 0 0" /> 

</Canvas> 

</Grid> 

</Page> 
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If you’re working in code, the Matrix structure has a Transform method that applies the transform 
to a Point value and returns the transformed Point. 

However, the Matrix structure is missing many amenities. It 7 s missing a multiplication operator 
that would allow you to easily perform your own matrix multiplications in code. You could write the 
multiplication code yourself, or you can use TronsformGroup, which internally performs matrix mul¬ 
tiplications and makes the result available in a read-only Value property of type Matrix. If you need 
to perform matrix multiplications, you can create a TransformGroup in code, add a couple initialized 
Transform derivatives to it, and access the Value property. 

I’ll have an important example in Chapter 13. Matrix transform calculations become essential in 
computing scaling and rotation centers when using touch to manipulate on-screen objects. 

The Composite Transform 

When combining transforms of various types, the order makes a difference. In practical use, however, 
it turns out that you usually want various transforms to be applied in a fairly standard order. 


The frequent references to .7 should more accurately be .707, the sine and cosine of 45 degrees and 
(not coincidently) half the square root of 2. These eight transforms result in each TextBlock being 
rotated an additional 45 degrees from the previous one: 
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For example, suppose you want to rotate, scale, and translate an element. ScaleTronsform usually 
comes first because generally you want to specify the scaling in terms of the unrotated element. 

The TronsloteTronsform comes last because generally you don’t want scaling or rotation to affect 
the translation factors. That means the RototeTronsform is in the middle. The order is: scale, rotate, 
translate. 

If that’s the order you want, you can use CompositeTransform. CompositeTronsform has a bunch of 
properties defined to perform transforms in the order: 

■ Scale 

■ Skew 

■ Rotate 

■ Translate 
The properties are 

■ CenterX and CenterY for the center of scaling, skewing, and rotation 

■ ScoleX and ScoleY 

■ SkewX and SkewY 

■ Rotation 

■ TranslateX and TranslateY 

Here’s a little program that uses a CompositeTronsform as a convenient way to combine scaling and 
skewing: 

Project: TiltedShadow I File: MainPage.xaml (excerpt) 

<Page … > 

<Page.Resources 〉 

〈Style TargetType="TextBlock"> 

〈Setter Property="Text" Val ue="qui rky" /> 

〈Setter Property="FontFami ly" Value="Times New Roman" /> 

〈Setter Property="FontSi ze" Value="192" /> 

〈Setter Property="Hori zontalA1ignment" Val ue="Center" /> 

〈Setter Property="Verti calA1ignment" Val ue="Center" /> 

</Style> 

</Page.Resources 〉 
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<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<!-- Shadow TextBlock --> 

<TextBlock Foreground="Gray" 

RenderT ransformOrigi n="0 1"> 

<TextBlock.RenderTransform> 

<CompositeTransform ScaleY="l. 5" SkewX="-60" /> 

</TextBlock.RenderTransform> 

</TextBlock> 


<!-- TextBlock with all styled properties --> 

〈TextBlock /> 

</Gri d> 

</Page> 

The XAML instantiates two TextBlock elements with mostly the same properties specified in the 
Style, including the Text property, and as far as the layout system is concerned, they both occupy the 
same space. The bottom one is gray, however, and has scale and skew transforms applied: 



Notice that the RenderTronsformOrigin is set to the point (0, 1), which means that the transform 
is relative to the lower-left corner. However, that point could be specified as (1, 1) or anything in 
between, and it would work the same. All that’s required is that the two TextBlock elements share the 
same bottom edge. A ScaleY of 1.5 is applied to increase the height of the shadow by 50 percent. The 
SkewX value of -60 degrees should shift the bottom to the left, but because the bottom is the center 
of scaling and skewing, the top is skewed to the right. 

Look closely and you’ll notice that the bottoms of the descenders don’t quite meet up. That’s 
because the TextBlock actually extends a little below the bottom of the descenders. Change the 
RenderTronsformOrigin to (0, 0.96) for a somewhat better match. 
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What if you wanted a similar effect with text with no descenders? Here’s an example: 



The problem is that you need to come up with a RenderTronsformOrigin with a Y value equal to 
the relative height of the text above the baseline. That’s dependent on the font. For this particular 
screenshot, I experimented until I came up with (0, 0.78), but that’s appropriate only for the Times 
New Roman font. To do something like this in a generalized way, you'd need access to font metrics, 
which are available to a Windows 8 application only through DirectX. I’ll show you how to do that in 
Chapter 15, "Going Native." 

Geometry Transforms 


The Geometry class defines a Transform property, which naturally raises the question: What is the 
difference between applying a transform to a Path element and applying a transform to a Geometry 
object that is set to the Data property of a Path? 


The big difference is that a Transform applied to the RenderTronsform property of a Path increases 
the width of the strokes, whereas a Transform applied to the Geometry does not. 

Here's a Path element based on a RectongleGeometry with a height and width of 10 but with a 
transform applied to the geometry to increase it by a factor of 20: 

〈Path Stroke="Black" 

StrokeThi ckness="l" 

StrokeDashArray="l 1"> 

<Path.Data> 

<RectangleGeometry Rect="0 0 10 10" 

Transform="20 0 0 20 0 0" /> 

〈 /Path.Data 〉 

</Path> 
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The result is as if the Red value in the RectongleGeometry had a height and width of 200: 



This XAML has the same initial RectangleGeometry but the transform is applied to the Path: 

〈Path Stroke="Black" 

StrokeThi ckness="l" 

StrokeDashArray="l 1" 

RenderT ransform="20 0 0 20 0 0"> 

<Path.Data> 

<RectangleGeometry Rect="0 0 10 10" /> 

</Path.Data> 

</Path> 


The result is quite different: 



To the layout system, however, these elements appear to be identical. Both Path elements are 
perceived to have a width and height of 10. 


Brush Transforms 


The Brush class defines two transform-related properties: Transform and RelotiveTronsform, which are 
distinguished by letting you specify translation factors based on the pixel size of the brush or relative 
to its size. RelotiveTransform is often easier to use unless you’ve given the brushed element a specific 
pixel size. 
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Here’s a program that replicates the RainbowEight program from Chapter 3, "Basic Event 
Handling," but using an animated brush transform. I've substituted a Path rendition of the 8 rather 
than using a TextBlock because I couldn’t get the brush to repeat with the SpreodMethod property of 
Repeat for a TextBlock. 


Project: RainbowEightTransform I File: MainPage.xaml (excerpt) 


<Page … > 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Viewbox> 

<Path StrokeThi ckness="50" 

Margin="0 25 0 0"> 

<Path.Data> 


<PathGeometry> 

<PathFigure StartPoi nt="110 0"> 

<ArcSegment Si ze="90 90" Poi nt="110 180" 
SweepDirecti on="Cl ockwise" /> 
<ArcSegment Si ze="110 110" Poi nt="110 400" 

SweepDirecti on="Countercl ockwise' 
<ArcSegment Si ze="110 110" Poi nt="110 180" 

SweepDirecti on="Countercl ockwise' 
<ArcSegment Si ze="90 90" Point="110 0" 

SweepDirecti on="Cl ockwise" /> 

</PathFigure> 

</PathGeometry> 

〈 /Path■Data> 

<Path.Stroke> 


/> 


/> 


<LinearGradientBrush StartPoi nt="0 0" EndPoint="l 1" 

SpreadMethod=" Repeat"> 

<LinearGradientBrush.RelativeTransform> 

<TranslateTransform x : Name="transl ate" /> 
</LinearGradientBrush.Relati veTransform> 


<GradientStop 
<GradientStop 
<GradientStop 
<GradientStop 
<GradientStop 
<GradientStop 
<GradientStop 
<GradientStop 


0ffset="0.00" 

0ffset="0.14" 

0ffset="0.28" 

0ffset="0.43" 

0ffset="0.57" 

0ffset="0.71" 

0ffset="0.86" 

0ffset="1.00" 


</LinearGradientBrush> 


</Path.Stroke> 


Color="Red" /> 
Color="0range" /> 
Color="Yellow" /> 
Color="Green" /> 
Color="Blue" /> 
Color="Indigo" /> 
Color="Violet" /> 
Color="Red" /> 


</Path> 


</Viewbox> 
</Grid> 


<Page.Triggers> 

<EventT rigger> 

<BeginStoryboard> 

<Storyboard> 

<DoubleAnimation Storyboard.TargetName=" translate" 

Storyboard.TargetProperty="Y" 

EnableDependentAnimati on="T rue" 
From="0" To="-l_36" Duration="0:0: 10" 
RepeatBehavior=" Forever" /> 
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</Storyboard> 
</BeginStoryboard> 
</EventTrigger> 
</Page.Triggers> 

</Page> 


Here’s the image: 



There’s a "magic number" in the markup. It’s the To value of the DoubleAnimation. That’s the value 
that is applied to the Y property of the TranslateTransform, and it was chosen so that the translated 
brush with that value is identical to the untranslated brush. The magic number, you can see, is -1.36, 
and I’m sure you want to know where it came from. 

If the LineorGrodientBrush went from top to bottom — with a Start Point of (0, 0) and an EndPoint 
of (0,1) — this To value would simply be -1. If the gradient went from left to right — with a StortPoint 
of (0, 0) and an EndPoint of (1, 0) — the X property of the TransloteTronsform would be the animation 
target, and again a To value of 1 or -1 would be used. 

But when the gradient goes from one corner to the opposite — with the default Start Point of (0, 0) 
and EndPoint of (1,1) — then that’s not quite right. When covering a Path element with a brush, the 
Windows Runtime computes a bounding rectangle that includes the geometric size of the element 
plus the stroke width. The brush is then stretched to this bounding rectangle: 
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The gradient line runs along the diagonal, which means that lines of constant color are at right angles 
to this gradient line. 

When the brush has a Spread Method oi Repeat, the brush conceptually repeats beyond the 
specified offsets. This SpreadMethod setting is useful when applying a TransloteTronsform to the brush 
because the brush seems to repeat regardless how it’s shifted. 

If you shift this brush up by the height of the element (that is, a Y value of -1 in the 
TranslateTransform), the bottom edge of the untransformed brush becomes the top edge of the 
transformed brush, but you can see the result in the following image, and it’s not the same as the 
previous image: 
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To get a smooth animation, you need to shift it up some more. But by how much? 


Let’s extend this figure to show part of the repeating brush, and let’s label the width of the 
element with 'w 7 , the height with 'h', the diagonal with 'd', and the increase in height with 7\h , . 



Ah 


w 



You can figure out Ah in a variety of ways, but perhaps the most straightforward is based on 
similar triangles: 

d _h-\- Ah 
h d 


from which it’s easy to derive 


•2 


Ah 


w 

h 


or, the number we really want: 


h-\- Ah 
h 


2 


1 + 


W 
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Try plugging in the numbers from the Path shown earlier. You’ll need to add the StrokeThickness to 
the widths and heights of the geometry. With a width of 270 and a height of 450, Ah is 162. Add that 
to h and divide by h, and that’s the magic number of 1.36. 

Would you like to hear about an easier approach? Simply use two DoubleAnimation objects in the 
Storyboard, where one targets the Y property and the other targets X. Set the To value of both to -1 
and the brush shifts both up and left with every cycle. 


Dude, Where's My Element? 

Earlier I mentioned that a computed Matrix \/a\ue is available from TronsformGroup, but it’s not 
available from other sources where you might expect it. For example, GenerolTronsform — from which 
Tronsform and all the other transform classes derive — might be expected to have a Matrix property, 
but it does not 

However, the G en era I Transform class has a Transform Point method and a TronsformBounds 
method, which applies the transform to a Rect value, and these actually come in handy in some 
circumstances. 

Suppose an element is a child of a panel. The panel is responsible for positioning the element 
relative to itself, but the element could also have a RenderTronsform applied with translation, scale, 
rotation, or skewing. For purposes of hit-testing, the location and orientation of that element are 
known internal to the system. But can your own program find where the element is actually located? 

Yes! The essential (but obscure) method is defined by UlElement and called TronsformToVisuol. 
Generally, you’ll call this method on an element with an argument that is the element’s parent or 
some other ancestor: 


GeneralTransform xform = element.TransformToVisual(parent); 

The G en era I Transform object returned from the method maps from element coordinates to parent 
coordinates. But you can’t actually see what this transform is! It won’t give you a Matrix value. All you 
can do with it is call TransformPoint or TronsformBounds or use the Inverse property. But this is often 
all you need. 

Here's a XAML file that animates properties of a CompositeTransform to make a TextBlock go crazy 
all over the screen: 


Project: WheresMyElement | File: MainPage.xaml (excerpt) 

<Page … > 

<Grid Name="contentGri d" 

Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<TextBlock Name="txtbl k" 

Text="Tap to Find" 

FontSi ze="96" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Center" 

RenderTransformOrigi n="0.5 0.5"> 
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<TextBlock.RenderTransform> 

<CompositeTransform x:Name=" transform" /> 
</TextBlock.RenderTransform> 

</TextBlock> 


〈Polygon Name="polygon" Stroke="Bl ue" /> 
〈Path Name="path" Stroke="Red" /> 

</Grid> 


<Page.Triggers> 

<EventTrigger> 

<BeginStoryboard> 

<Storyboard x :Name="storyboard"> 

<DoubleAnimation Storyboard.TargetName=" transform" 

Storyboard.TargetProperty="T ranslateX" 
From="-300" To= n 300" Duration="0:0:2. 11" 
AutoReverse="T rue" RepeatBehavior=" Forever" /> 
<DoubleAnimation Storyboard.TargetName=" transform" 

Storyboard.TargetProperty="T ranslateY" 
From="-300" To="300" Durati on="0 :0:2.23" 


AutoReverse="True" RepeatBehavior=" Forever" /> 
<DoubleAnimation Storyboard.TargetName=" transform" 

Storyboard.TargetPrope rty="Rotati on" 

From= M 0" To="360" Duration="0:0: 2.51" 
AutoReverse="T rue" RepeatBehavior=" Forever" /> 
<DoubleAnimation Storyboard.TargetName=" transform" 

Storyboard.TargetProperty=" SealeX" 

From= ,, l" To="2" Duration= M 0:0: 2.77" 
AutoReverse="T rue" RepeatBehavior=" Forever" /> 
<DoubleAnimation Storyboard.TargetName=" transform" 

Storyboard.TargetProperty=" SealeY" 

From="l" To="2" Duration= M 0:0:3.07" 


AutoReverse="T rue" RepeatBehavior=" Forever" /> 
<DoubleAnimation Storyboard.TargetName=" transform" 

Storyboard.TargetPrope rty="SkewX" 

From="-30" To="30" Duration="0:0: 3.31" 
AutoReverse="T rue" RepeatBehavior=" Forever" /> 
<DoubleAnimation Storyboard.TargetName=" transform" 

Storyboard.TargetPrope rty="SkewY" 

From="-30" To="30" Durati on="0 :0:3.53" 
AutoReverse="T rue" RepeatBehavior=" Forever" /> 

</Storyboard> 

</BeginStoryboard> 

</EventTrigger> 

</Page.Triggers> 

</Page> 


Notice that the Grid also contains a blue Polygon and a red Path, but with no actual coordinate points. 

The code-behind file uses the Topped event to take a "snapshot” of the TextBlock by calling 
TronsformToVisuol and pausing the Storyboard (resumed on the next tap). TronsformToVisuol returns 
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a GenerolTransform object that describes the relationship between the TextBlock and the Grid. The 
program uses this to transform the four corners of the TextBlock to Grid coordinates for the Polygon, 
which effectively draws a rectangle around the TextBlock: 


Project: WheresMyElement I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

bool storyboardPaused; 

public MainPageO 

{ 

this .Ini tializeComponent(); 

} 


protected override void OnTapped(TappedRoutedEventArgs args) 

{ 

if (storyboardPaused) 

{ 

storyboard.ResumeC); 
storyboardPaused = false; 
return ; 

} 


} 


General Transform xform = txtblk.TransformToVisual(contentGrid); 


// Draw blue polygon around element 
polygon.Points.Cl ear(); 

polygon.Points.Add(xform.TransformPoi nt(new 
polygon.Points.Add(xform.TransformPoi nt(new 
polygon.Points.Add(xform.TransformPoi nt(new 

polygon.Points.Add(xform.TransformPoi nt(new 


Point (0, 0))); 

Poi nt(txtblk.ActualWidth, 0))); 
Point (txtblk.ActualWidth, 

txtblk.ActualHeight))); 

Poi nt(0, txtblk.Actual Height))); 


// Draw red bounding box 

path.Data = new RectangleGeometry 

{ 

Rect = xform.TransformBounds(new Rect(new Poi nt(0 , 0 )， txtblk.DesiredSize)) 

}； 


storyboard. PauseO ; 
storyboardPaused = true ; 
base.OnTapped(args); 
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The call to TronsformBounds obtains something a little different: a rectangle describing a boundary 
box with sides parallel to the horizontal and vertical large enough to encompass the element. This is 
drawn in red: 



That boundary rectangle is easily calculable from the maximum and minimum X and Y coordinates of 
the transformed four corners, but it’s nice to have it conveniently available. 

Projection Transforms 

Earlier in this chapter I discussed why a two-dimensional graphics transform is mathematically 
described by a 3x3 matrix and requires a flirtation with the third dimension. By a similar analogy, a 
three-dimensional graphics transform is expressed by a 4x4 matrix, and the Windows Runtime has 
one. 

The Windows. Ul.Xoml. Medio. Medio 3D namespace contains exactly two items: a Matrix3D structure 
available for all programmers, and a Motrix3DHelper class that’s mostly of value to C++ programmers 
because they can’t access any of the methods defined by Matrix3D. The properties of Matrix3D are 
analogous to those in the regular Matrix structure except that every cell of the matrix is available: 
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However, few programmers ever really get close to this matrix. Most of them are content to use the 
PlaneProjection class that I briefly demonstrated at the beginning of this chapter. 
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PlaneProjection is intended mostly to let you rotate two-dimensional elements in three- 
dimensional space. Rotation in 3D space is always around an axis, and PlaneProjection lets you rotate 
an element around a horizontal axis (using the RototionX property), the vertical axis (with RotationY), 
or the Z axis that conceptually pokes out of the screen. Rotation around the Z axis is simply two- 
dimensional rotation, so that’s not nearly as exciting as the other two. 


You can anticipate the direction of rotation using the right-hand rule: Point the thumb of your 
right hand in the direction of the positive axis. That’s right for the X axis, down for the Y axis, and out 
of the screen for Z The curve of your fingers indicates the direction of rotation for positive angles. 
PlaneProjection applies the rotations in the order X, Y, and Z, but generally you’ll be using only one of 
them. 

With a little discreet use of PlaneProjection, you can have elements swing into view or even 
conceptually flip over to reveal something on the "other side" (as I’ll demonstrate shortly). 

And then there’s the not-so-discreet uses. The ThreeDeeSpinningText program lets you 
independently animate the RototionX, RototionY, and RototionZ properties to spin a TextBlock around 
in 3D space. Here’s the XAML file with a group of Begin/Stop and Play/Pause buttons at the bottom: 


Project: ThreeDeeSpinningText I File: MainPage.xaml (excerpt) 

<Page … > 

<Page.Resources 〉 

〈Storyboard x:Key="xAxi sAnimation" RepeatBehavior="Forever"> 
<DoubleAnimation Storyboard .TargetName="proj ection" 

Storyboard.TargetPrope rty="Rotati onX" 
From="0" To="B60" Duration="0:0: 1.9" /> 

</Storyboard> 


<Storyboard x:Key="yAxi sAnimation" RepeatBehavior="Forever"> 
<DoubleAnimation Storyboard .TargetName="proj ection" 

Storyboard .TargetProperty="RotationY" 
From="0" To="B60" Duration="0:0: 3.1" /> 

</Storyboard> 


〈Storyboard x:Key="zAxi sAnimation" RepeatBehavior="Forever"> 
<DoubleAnimation Storyboard .TargetName="proj ection" 

Storyboard.TargetPrope rty="Rotati onZ" 
From="0 M To="360" Durati on="0 :0:4.3" /> 

</Storyboard> 

</Page.Resources> 


<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Crid.RowDefinitions> 

〈RowDefinition Height:"*" /> 

<RowDefinition Hei ght="Auto" /> 

</Grid.RowDefinitions> 

〈TextBlock Text="3D-i sh" 

FontSize="384" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Center"> 

<TextBlock.Projection 〉 
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<P1aneProjection x:Name="projection" /> 
</TextBlock.Projection> 

</TextBlock> 


<!-- Control Panel --> 

〈Grid Grid.Row="l" HorizontalA1i gnment="Center"> 
<Grid.RowDefinitions> 

<RowDefinition Hei ght="Auto" /> 

〈RowDefinition Hei ght="Auto" /> 

〈RowDefinition Hei ght="Auto" /> 

</Grid.RowDefinitions> 


<Grid.ColumnDefinitions> 

<ColumnDefinition Wi dth="Auto" /> 

<ColumnDefinition Wi dth="Auto" /> 

<ColumnDefinition Wi dth="Auto" /> 

</Grid.ColumnDefinitions> 

<Grid.Resources 〉 

〈Style TargetType="TextBlock"> 

〈Setter Property="FontSi ze" 

Val ue="{StaticResource ControlContentThemeFontSi ze}" /> 
〈Setter Property="Verti calA1ignment" Val ue="Center" /> 

</Style> 


<Style TargetType=" Button"> 

〈Setter Property="Wi dth" Value="120" /> 
〈Setter Property="Margi n" Value="12" /> 
</Style> 

</Grid.Resources 〉 


<TextBlock Text="X Axis: ” Grid. Row="0" Grid.Col umn="0" 
Tag="xAxi sAnimation" /> 

〈Button Content="Begi n" Grid. Row="0" Grid.Col umn="l" 

Cli ck="OnBegi nStopButton" /> 

〈Button Content="Pause" Grid. Row="0" Grid.Col umn="2" 
IsEnabl ed="Fal se" 

Cli ck="OnPauseResumeButton" /> 

<TextBlock Text="Y Axis: ” Grid.Row="l" Grid.Col umn="0" 
Tag="yAxi sAnimation" /> 

〈Button Content="Begi n" Grid. Row="l" Grid.Col umn="l" 

Cli ck="OnBegi nStopButton" /> 

〈Button Content="Pause" Grid. Row="l" Grid.Col umn="2" 
IsEnabl ed="Fal se" 

Cli ck="OnPauseResumeButton" /> 

<TextBlock Text="Z Axis: ” Grid.Row="2" Grid.Col umn="0" 
Tag="zAxi sAnimation" /> 

〈Button Content="Begi n" Grid. Row="2" Grid.Col umn="l" 

Cli ck="OnBegi nStopButton" /> 

〈Button Content="Pause" Grid. Row="2" Grid.Col umn="2" 
IsEnabl ed="Fal se" 

Cli ck="OnPauseResumeButton" /> 

</Grid> 

</Grid> 

</Page> 
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The durations of the individual DoubleAnimation objects all have somewhat different times to 
avoid repetitive patterns when they're all going at once. The buttons in the code-behind file use the 
Begin, Stop, Pause, and Resume methods of Storyboard to control the activity: 


Project: ThreeDeeSpinningText I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

public MainPageO 

{ 

this .Ini tializeComponent(); 

} 

void OnBeginStopButton (object sender, RoutedEventArgs args) 

{ 

Button btn = sender as Button ; 

string key = GetSibling(btn, -1).Tag as string; 

Storyboard storyboard = this .Resources[key] as Storyboard; 
Button pauseResumeButton = GetSibling(btn, 1) as Button ; 
pauseResumeButton.Content = "Pause" ; 

if (btn.Content as string == "Begin ”） 

{ 

storyboard.Begin(); 
btn.Content = "Stop" ; 
pauseResumeButton.IsEnabled = true; 

} 

else 

{ 

storyboard.Stop(); 
btn.Content = "Begin ”； 
pauseResumeButton.IsEnabled = false; 

} 

} 

void OnPauseResumeButton (object sender, RoutedEventArgs args) 

{ 

Button btn = sender as Button ; 

string key = GetSibling(btn ， -2).Tag as string; 

Storyboard storyboard = this. Resources[key] as Storyboard ; 

if (btn.Content as string == "Pause") 

{ 

storyboard.Pause(); 
btn.Content = "Resume" ; 

} 

else 

{ 

storyboard. ResumeO ; 
btn.Content = "Pause" ; 

} 

} 


FrameworkElement GetSibli ngCFrameworkEl ement element, int relativelndex) 


Panel parent = element.Parent as Panel ; 
int index = parent.Chi 1dren.IndexOf(element); 
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} 


} 


return parent.Children[index + relativelndex] as FrameworkElement ; 


And here’s a sample image: 



The PlaneProjection class has a bunch of additional properties. The CenterOfRotationX and 
CenterOfRototionY properties are both in coordinates relative to the element. The default values are 
0.5, which is the center of the element and usually what you want. The CenterOfRototionZ property is 
in pixels with a default value of 0, corresponding to the surface of the screen. For purposes of internal 
calculations, it is assumed that the "camera" (or you, the user) is viewing the screen from a distance of 
1000 pixels, or about 10 inches. 

PlaneProjection also defines three LocolOffset properties for theX, Y, and Z dimensions and three 
GlobalOffset properties. These are translation factors in pixels. The LocolOffset values are applied 
before the rotation, and the GlobalOffset values are applied after the rotation. Most often, you’ll be 
setting the GlobalOffset properties. 

Here's a little example of a "flip panel," a technique that was once quite difficult and involved real 
3D programming. The idea is that you have a little collection of controls on a panel and a way to flip 
that panel over to use a different (but related) set of controls. In this example, I’ve represented the 
front and "back" of this panel with two Grid panels with different background colors containing a 
TextBlock each: 


Project: TapToFlip I File: MainPage.xaml (excerpt) 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Grid HorizontalAli gnment="Center" 

VerticalAli gnment="Center" 

Tapped="OnGri dTapped"> 

<Grid Name="gri dl" 
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Background="Cyan" 

Canvas .ZIndex="l"> 

〈TextBlock Text="Hello" 

HorizontalAli gnment="Center" 
FontSize="192" /> 

</Crid> 

<Crid Name="gri d2" 

Background="Yel 1ow" 

Canvas .Zlndex="0"> 

〈TextBlock Text="Wi ndows 8" 
FontSize="192" /> 

</Gri d> 


<Grid.Projection> 

<PlaneProjection x:Name="projecti on" /> 
</Grid.Proj ection> 

</Grid> 

</Grid> 


Notice the Canvas.Zlndex settings. These ensure that the gridl is visually on top of grid2 even though 
it comes earlier in the children collection of their mutual parent. 

The Resources section contains two Storyboard definitions, one to flip and the other to flip back: 


Project: TapToFlip | File: MainPage.xaml (excerpt) 

<Page.Resources 〉 

<Storyboard x:Key="fl ipStoryboard"> 

<Doubl eAni mati onllsi ngKeyFrames 

Storyboard.TargetName=" projection" 

Storyboard.TargetPrope rty="RotationY"> 

<DiscreteDoubleKeyFrame KeyTime="0:0:0" Value="0" /> 

<LinearDoubleKeyFrame KeyTi me="0 :0:0.99" Value="90" /> 

<DiscreteDoubleKeyFrame KeyTi me="0 : 0:1.01" Value="-90" /> 
<LinearDoubleKeyFrame KeyTime="0:0:2" Value="0" /> 

</Doubl eAni mati onllsi ngKeyFrames> 

<DoubleAnimation Storyboard .TargetName="proj ecti on" 

Storyboard.TargetPrope rty="Global OffsetZ" 
From="0" To="-1000" Duration= M 0:0:l" 
AutoReverse="True" /> 

<ObjectAnimati onllsi ngKeyFrames 

Storyboard.TargetName="gri dl" 

Storyboard■TargetPrope rty=" (Canvas.ZIndex)"> 
<DiscreteObjectKeyFrame KeyTime="0:0:0" Value="l" /> 

<DiscreteObjectKeyFrame KeyTi me="0 :0:1" Value="0" /> 

</0bj ectAni mati onllsi ngKeyFrames 〉 

<0bj ectAni mati onllsi ngKeyFrames 

Storyboard.TargetName="gri d2" 

Storyboard■TargetPrope rty=" (Canvas.ZIndex)"> 
<DiscreteObjectKeyFrame KeyTi me="0: 0:0" Value="0" /> 

<DiscreteObjectKeyFrame KeyTi me="0 :0:1" Value="l" /> 

</0bj ectAni mati onllsi ngKeyFrames 〉 

</Storyboard> 
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<Storyboard x: Key="fl ipBackStoryboard"> 

<Doubl eAni mati onllsi ngKeyFrames 

Storyboard.TargetName=" projection" 

Storyboard.TargetPrope rty="RotationY"> 

<DiscreteDoubleKeyFrame KeyTime="0:0:0" Value="0" /> 

<LinearDoubleKeyFrame KeyTi me="0 :0:0.99" Value="-90" /> 
<DiscreteDoubleKeyFrame KeyTi me="0 :0:1.01" Value="90" /> 
<LinearDoubleKeyFrame KeyTime="0:0:2" Value="0" /> 

</DoubleAnimationUsingKeyFrames> 

<DoubleAnimation Storyboard.TargetName=" projection" 

Storyboard.TargetPrope rty="Global OffsetZ" 
From="0" To="-1000" Duration="0 :0:1" 
AutoReverse="True" /> 

<0bjectAnimationUsingKeyFrames 

Storyboard .TargetName="gri dl" 

Storyboard■TargetPrope rty=" (Canvas.ZIndex)"> 
<DiscreteObjectKeyFrame KeyTime="0:0:0" Value="0" /> 

<DiscreteObjectKeyFrame KeyTi me="0 :0:1" Value="l" /> 

</0bjectAnimationUsingKeyFrames> 


<0bjectAnimationUsingKeyFrames 

Storyboard .TargetName="gri d2" 

Storyboard.TargetPrope rty=" (Canvas.ZIndex)"> 
<DiscreteObjectKeyFrame KeyTime="0:0:0" Value="l" /> 

<DiscreteObjectKeyFrame KeyTi me="0: 0:1" Value="0" /> 

</0bjectAnimationUsingKeyFrames> 

</Storyboard> 

</Page.Resources 〉 


These two storyboards are very similar. Each of them contains a DoubleAnimotionilsingKeyFromes 
to target the RotationY property of the PlaneProjection object. The property is rotated from 0 to 
either 90 or -90 degrees (at which point it's at right angles to the user), and then it's switched 180 
degrees so that the animation can continue in the same direction back to 0. 

At the same time, the GlobalOffsetZ property is animated from 0 to -1000 and back to 0. This 
makes it seem as if the panel is dropping behind the screen in preparation for performing the flip 
(perhaps so that the flipping panel won’t smack the user in the nose). 


Halfway through each Storyboard, the Canvas.ZIndex indices are swapped. The Canvas.ZIndex 
property is another appropriate target of an ObjectAnimationilsingKeyFromes. 

The animations are triggered by a tap, which is handled in the code-behind file: 


Project: TapToFlip I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

Storyboard flipStoryboard, flipBackStoryboard; 
bool flipped = false; 

public MainPageQ 
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this .Ini tializeComponent(); 

flipStoryboard = this .Resources ["fl ipStoryboard"] as Storyboard ; 

flipBackStoryboard = this .Resources ["flipBackStoryboard"] as Storyboard; 


void OnGri dTapped(object sender, TappedRoutedEventArgs args) 

{ 

if (flipStoryboard.GetCurrentStateO == ClockState. Active || 
flipBackStoryboard.GetCurrentStateC) == ClockState. Active) 

{ 

return ; 

} 

Storyboard storyboard = flipped ? f1ipBackStoryboard : flipStoryboard; 
storyboard.Begin(); 
flipped a= true; 



Much of the logic here is to prevent one Storyboard from starting when the previous one hasn’t yet 
finished. With the way these storyboards are defined, that would cause discontinuities. (Try removing 
the return statement from OnGridTopped to see the unsatisfactory result.) I would prefer that a tap 
while an animation is in progress simply reverses the operation, but that would require somewhat 
more complex logic. 

Deriving a Matrix3D 


Let's get into some hairy math, OK? 

As you discovered earlier, two-dimensional graphics requires a 3x3 transform matrix to 
accommodate translation as well as scaling, rotation, and skew. Conceptually, a point [x, y) is treated 
as if it exists in 3D space with the coordinates [x, y, 1). 


The application of the generalized two-dimensional affine transform looks like this: 


x y 
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Those are the actual fields of the Matrix structure provided for this purpose. The fixed third column 
restricts it to affine transforms. The transform formulas implied by the matrix multiplication are 


x r =MU-x + M2\-y + OffsetX 
/ =Ml2-x^M22-y + OffsetY 
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Because this is an affine transform, a square is always transformed into a parallelogram. This 
parallelogram is defined by three corners, and the fourth corner is determined by the other three. 

Is it possible to derive the affine transform that maps a unit square into an arbitrary parallelogram? 
What we want is a mapping like this: 


(0,0) 4 ( x 0 , 凡） 

(0,1) 4 (xj) 

(l,0)^(x 2 ,;； 2 ) 

If you begin substituting these points into the transform formulas, it is easy to derive the following 
cells of the required matrix: 


Ml 1 = x 2 - x 0 
M\2 = y 2 -y 0 
M21 = -x 0 

Mil = y x -y^ 

OffsetX = x 0 
OffsetY = y Q 

In 3D graphics programming, a 4x4 transform matrix is required and a point (x, y, z) is treated as if 
it exists in 4D space with coordinates [x,y, z, 1). Because there are no remaining letters after x, y, and 
z, that fourth dimension is usually referred to with the letter w. Application of a transform looks like 
this: 


x y z 
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Those are the actual fields of the Matrix3D structure. 




〆 z r 


W 


That resultant 4x1 matrix is then converted back to a point in three-dimensional space by dividing 
all the coordinates by w'\ 



W 



^ 

vJ " W " W ^ 


In conventional 2D graphics, a potential division by zero is generally undesired. But in 3D graphics, 
division by a value that might equal zero is essential because this is how perspective is achieved. You 
want parallel lines to meet at infinity because that’s how the world looks in real life. 
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The only purpose of this Motrix3D structure in the Windows Runtime is to set to the 
Projection Mo trix property of a Matrix3DProjection object, which you can then set to the Projection 
property of an element as an alternative to PlaneProjection. In XAML, it might look like this: 


<Image … > 

<Image.Projecti on> 

<Matrix3DProjecti on> 

<Matrix3DProjection.Projecti onMatrix> 
1000 , 0100 , 0010 , 0001 
</Matrix3DProjection.ProjectionMatrix> 
</Matrix3DProjecti on> 

</Image.Projecti on> 

</Image> 


You can’t actually instantiate a Matrix 3D value in XAML, so instead you need to specify the 16 
numbers that make up the matrix, starting with the first row. This example shows the identity matrix, 
with its characteristic diagonal of Is. 

This full-blown 4x4 matrix isn’t entirely used in this context because the element that it’s applied 
to is flat and has a Z coordinate of zero, so the application of the matrix really looks like this: 


x y 0 
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This means that the cells that make up the entire third row — the values of M31, M32, M33, and M34 — 
are irrelevant. They are multiplied by 0 and hence do not enter the calculation. 


Moreover, the 3D point derived from this process is collapsed on the Z axis to obtain a 2D point for 
mapping to the video display: 



This is a process that happens in standard 3D graphics as well, but there’s usually much more work 
involved because the Z values also indicate what’s visible to the camera and what’s obscured. 


Moreover, in standard 3D graphics, only a range of Z values is retained. A "near plane" and "far 
plane" are defined in terms of Z, and only coordinates between these two planes are visible. The rest 
are simply thrown away because they are conceptually too near or too far from the camera. In the 
Windows Runtime, only coordinates with Z values between the values of 0 and 1 are retained. To 
avoid losing part of a transformed element, M13 and M23 should be set to zero. OffsetZ can be set to 
any value between 0 and 1, but it’s convenient to set it to zero as well. 
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When applying a Matrix3DProjection to a two-dimensional element, the transform formulas are 
therefore 

x f =Mll-x + M2l-y + OffsetX 
/ =M12 .x + M22 • y + OffsetY 
W =M14 -X + M24 •少 + 綱 4 

If M14 and M24 are zero and M44 is 1, this is simply a two-dimensional affine transform. Nonzero 
values of M14 and M24 are the non-affine parts of these formulas. M44 can be something other than 
1, but if it’s not zero, you can always find an equivalent transform where M44 equals 1. Just multiply 
all the fields by 1/M44. 

With a non-affine transform, a square is not necessarily transformed to a parallelogram. However, 
a non-affine matrix transform still has limitations. It can’t transform a square to any arbitrary 
quadrilateral. The transformed lines cannot cross each other and the four angles must be convex. 

Let’s attempt to derive a non-affine transform that maps the four corners of a square to four 
arbitrary points: 

( 0 , 0 )4(Wo) 

( 0 , 1 ) 

(1 ， 0) —(x 2 , 少 2 ) 

(U) — (W 3 ) 

This exercise will be easier if we break this down into two transforms: 

(0,0) (0,0) (x 0 ,y 0 ) 

(0 ， 1) — (0,1) ^ ( 又 i ， 7i) 

(1 ， 0) 4 (1,0) ^ (x 2 ,_y 2 ) 

The first transform is obviously a non-affine transform that I’ll call B. The second is something 
that well force to be an affine transform called A (for affine). The way we’ll force it to be an affine 
transform is by deriving values of a and b. The composite transform is BxA. 

I’ve already shown you the derivation of the affine transform, and I don’t even need to change 
notation when switching from the 3x3 matrix to the 4x4 matrix. But we also want this affine transform 
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to map the point (a, b) to the arbitrary point (x 3 , y 3 ). By applying the derived affine transform to [a, b) 
and solving for a and b, we get this: 

_M22-x 3 -M2l -y.+Mll-OffsetY- M22 - OffsetX 
a — MU-M22-M12-M21 

b _ MU-y.-MU-x. + Mn-OffsetX - MU-OffsetY 

— MU-M22-M12 -M21 

Now let’s take a shot at the non-affine transform, which needs to yield the following mappings: 

( 0 , 0 ) —( 0 , 0 ) 

(0，1) —(0,1) 

( 1 , 0 ) ^( 1 , 0 ) 

(1,1) ^ (a,Z?) 

Here are the transform formulas from earlier: 
x r =MU-x + M2\ • y + OffsetX 
y r =M\2-x + M22-y + OffsetY 
W = M14 • x + M24 • y + M44 

Keep in mind that x' and y' must be divided by w' to get the transformed point. 

If (0 ; 0) maps to (0, 0), then OffsetX and OffsetY are zero and M44 is nonzero. Let’s go out on a 
limb and set M44 to 1. 

If (0, 1) maps to (0,1), then M21 must be zero (to calculate a zero value of x') and y' divided by w' 
must equal 1, which means M24 equals M22 minus 1. 

If (1, 0) maps to (1, 0), then M12 is zero (for the zero value of y’）and divided by W must equal 1, 
or M14 equals Mil minus 1. 

If (1, 1) maps to (a, b), then a bit of algebra derives 


Mll = 


a 

ci b 一 1 


M22 = 


b 

ci b _ 1 


And a and b have already been derived. 
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Now let’s code it up. I want to display the actual matrix that’s derived from this process. That’s the 
purpose of a User Control derivative named DisployMotrix3D. The XAML file consists of little more 
than a 4x4 Grid of TextBlock elements: 


Project: NonAffineStretch | File: DisplayMatrix3D.xaml (excerpt) 

<UserControl … > 

<UserControl.Resources 〉 

〈Style TargetType="TextBlock"> 

〈Setter Property="TextAl ignment" Val ue="Ri ght" /> 
〈Setter Property="Margi n" Value="6 0" /> 

</Style> 

</UserControl.Resources 〉 


<Border BorderBrush="{Stati cResource ApplicationForegroundThemeBrush} 
BorderThi ckness="l 0"> 

<Gri d> 

<Grid.RowDefinitions> 

〈RowDefinition Height="Auto" /> 

〈RowDefinition Height="Auto" /> 

〈RowDefinition Height="Auto" /> 

〈RowDefinition Hei ght="Auto" /> 

</Grid.RowDefinitions> 


<Grid.ColumnDefinitions> 


<ColumnDefinition 

Wi dth="Auto" 

/> 


<ColumnDefinition 

Wi dth="Auto" 

/> 


<ColumnDefinition 

Wi dth="Auto" 

/> 


<ColumnDefinition 

Wi dth="Auto" 

/> 


</Grid.ColumnDefinitions> 



〈TextBlock 

Name="mll" 

Grid.Row="0" 

Grid.Column="0" 

/> 

〈TextBlock 

Name="ml2" 

Grid.Row="0" 

Grid.Column="l" 

/> 

〈TextBlock 

Name="ml3" 

Grid.Row="0" 

Grid.Column:" 2" 

/> 

〈TextBlock 

Name="ml4" 

Grid.Row="0" 

Grid.Column="3" 

/> 

〈TextBlock 

Name="m21" 

Grid.Row="l" 

Grid.Col umn="0" 

/> 

〈TextBlock 

Name="m22" 

Grid.Row="l" 

Grid.Column="l" 

/> 

〈TextBlock 

Name="m23" 

Grid.Row="l" 

Grid. Column:'' 2" 

/> 

〈TextBlock 

Name="m24" 

Grid.Row="l" 

Grid.Column:" 3" 

/> 

〈TextBlock 

Name="m31" 

Grid.Row="2" 

Grid.Col umn="0" 

/> 

〈TextBlock 

Name="m32" 

Grid.Row="2" 

Grid.Column="l" 

/> 

〈TextBlock 

Name="m33" 

Grid.Row="2" 

Grid. Column:'' 2" 

/> 

〈TextBlock 

Name="m34" 

Grid.Row="2" 

Grid.Column="3" 

/> 

〈TextBlock 

Name="m41" 

Grid.Row="3" 

Grid.Col umn="0" 

/> 

〈TextBlock 

Name="m42" 

Grid.Row="3" 

Grid.Column="l" 

/> 

〈TextBlock 

Name="m43" 

Grid.Row="3" 

Grid.Column="2" 

/> 

〈TextBlock 

Name="m44" 

Grid.Row="3" 

Grid.Column="3" 

/> 


</Gri d> 
</Border> 
</UserControl > 
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The code-behind file defines a dependency property of type Motrix3D, so it receives a notification 
whenever the property is changed. Watch out: The notification will not occur if a property of the 
existing Motrix3D structure is changed. The entire structure must be replaced. 


Project: NonAffineStretch | File: DisplayMatrix3D.xaml.cs (excerpt) 

public sealed partial class DisplayMatrix3D : UserControl 

{ 

static DependencyProperty matrix3DProperty = 

DependencyProperty. Register( "Matrix3D" , 

typeof (Matrix3D ) ， typeof (Di splayMatri x3D ) ， 

new PropertyMetadata(Matrix3D. Identity, OnPropertyChanged)); 


public DisplayMatrix3D() 

{ 

this. InitializeComponent(); 

} 


public static DependencyProperty Matrix3DProperty 

{ 

get { return matrix3DProperty; } 

} 

public Matrix3D Matrix3D 

{ 

set { SetValue(Matrix3DProperty, value); } 

get { return (Matri x3D)GetValue(Matrix3DProperty); } 

} 

static void OnPropertyChanged(DependencyObject obj, 

DependencyPropertyChangedEventArgs args) 

{ 

(obj as DisplayMatri x3D) .OnPropertyChanged(args); 

} 


void OnPropertyChanged (DependencyPropertyChangedEventArgs args) 


mil.Text 
ml2.Text 
ml3.Text 
ml4.Text 


this .Matrix3D.Mil.ToString("F3") 
this .MatriX3D.M12.ToString("F3") 
this .Matrix3D.M13.ToString("F3") 
this .Matrix3D.M14.ToString("F6") 


m21.Text 
m22.Text 
m23.Text 
m24.Text 


this .Matrix3D.M21.ToString("FB") 
this .MatriX3D.M22.ToString("F3") 
this .MatriX3D.M23.ToString("F3") 
this .MatriX3D.M24.ToString("F6") 


m31.Text 
m32.Text 
m33.Text 
m34.Text 


thi s .Matrix3D.M31.ToString("F3") 
thi s .MatriX3D.M32.ToString("F3") 
this .MatriX3D.M33.ToString("F3") 
this .MatriX3D.M34.ToString("F6") 


m41_Text = 
m42.Text = 
m43.Text = 
m44.Text = 


this .Matrix3D.0ffsetX.ToString("F0"); 
this .Matrix3D.OffsetY.ToString("F0"); 
this .Matrix3D.0ffsetZ.ToString("F0"); 
this .MatriX3D.M44.ToString("F0"); 


} 


} 
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The formatting specifications were chosen based on a bit of experience with the common ranges of 
these cells. 

The XAML file for Main Page includes an instance of the DisplayMatrix3D control, but it also 
references an image from my website and adorns it with four Thumb controls. These Thumb controls 
allow us to drag any corner to an arbitrary location. The prefixes "ul", 〃 ur", "II", and "lr 〃 stand for 
"upper-left,” "upper-right," "lower-left," and "lower-right." 


Project: NonAffineStretch | File: MainPage.xaml (excerpt) 

<Page … > 

<Page.Resources 〉 

<Style TargetType="Thumb"> 

〈Setter Property="Wi dth" Value="48" /> 

〈Setter Property="Hei ght" Value="48" /> 

〈Setter Property="Hori zontalA1ignment" Val ue="Left" /> 
〈Setter Property="Verti calA1ignment" Val ue="Top" /> 
</Style> 

</Page.Resources 〉 


<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
〈Image Sou rce="http: //mm. charlespetzold.com/pw6/Petzold]ersey.jpg" 
Stretch="None" 

HorizontalA1i gnment="Left" 

VerticalAli gnment="Top"> 

<Image.Projection 〉 

<Matrix3DProjection x : Name="matri xProjection" /> 

</Image.Projection> 

</Image> 


〈Thumb DragDel ta="OnThumbDragDelta"> 

<Thumb.RenderTransform> 

<TransformGroup> 

<TranslateTransform X="-24" Y="-24" /> 

<TranslateTransform x : Name=" ulTrans1 ate" X="100" Y="100" /> 
</TransformGroup> 

</Thumb.RenderTransform> 

</Thumb> 

〈Thumb DragDel ta="OnThumbDragDelta"> 

<Thumb.RenderTransform> 

<T ransformGroup> 

<TranslateTransform X="-24" Y="-24" /> 

<T ranslateT ransform x : Name="u rT ranslate" X="420" Y="100" /> 
</TransformGroup> 

</Thumb.RenderTransform> 

</Thumb> 

〈Thumb DragDel ta="OnThumbDragDelta"> 

<Thumb.RenderTransform> 

<TransformGroup> 

<TranslateTransform X="-24" Y="-24" /> 

<T ranslateT ransform x : Name="l lTranslate" X="100" Y="500" /> 
</TransformGroup> 

</Thumb.RenderTransform> 

</Thumb> 
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〈Thumb DragDel ta="OnThumbDragDelta"> 

<Thumb.RenderTransform> 

<TransformGroup> 

<TranslateTransform X="-24" Y="-24" /> 

<TranslateTransform x:Name=""l 「 Translate” X="420" Y="500" /> 
</TransformGroup> 

</Thumb.RenderTransform> 

</Thumb> 


<local : DisplayMatrix3D HorizontalA1i gnment="Ri ght" 

Vertical ATi gnment="Bottom" 
FontSize="24" 


</Grid> 


Matri x3D="{Binding El ementName=matrixProjecti on, 

Path=Projecti onMatrix}" /> 


</Page> 


The code-behind file implements the math I just showed you, except that another matrix is needed 
for mapping from the actual size and location of the image to a unit square. That's the matrix called S 
in the CalculoteNewTronsform code: 


Project: NonAffineStretch | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

// Location and Size of Image with no transform 
Rect imageRect = new Rect(0, 0, 320, 400); 

public MainPageO 

{ 

this .Ini ti alizeComponent(); 

Loaded += (sender, args)=> 

{ 

CalculateNewTransform(); 

}； 

} 

void OnThumbDragDelta(ob ject sender, DragDeltaEventArgs args) 

{ 

Thumb thumb = sender as Thumb; 

TransformGroup xformGroup = thumb.RenderTransform as TransformGroup; 

T ranslateT ransform translate = xformGroup.Chi 1dren[1] as T ranslateT ransform ; 

translate.X += args.HorizontalChange; 
translate.Y += args.Vertical Change; 

CalculateNewTransform(); 

} 


void CalculateNewTransformC) 



Matrix3D matrix = CalculateNewTransform(imageRect, 

new Poi nt(ulTranslate.X, ulTranslate.Y), 
new Poi nt(urTranslate.X, urTranslate.Y), 


new Point (11Translate .X ， 1lTranslate.Y), 
new Poi nt(l 「 Translate .X ， 1rTranslate.Y)); 
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} 


matrixProjection.ProjectionMatrix = matrix; 


// The returned transform maps the points (0 ， 0 )， 

// (0 ， 1), (1 ， 0 )， and (1 ， 1) to the points 

// ptUL, ptUR, ptLL, and ptLR normalized based on rect. 

static Matrix3D CalculateNewTransform(Rect rect, Point ptUL, Point ptUR, 

Point ptLL, Point ptLR) 

{ 

// Scale and translate normalization transform 

Matrix3D S = new Matri x3D() 

{ 

Mil = 1 / rect.Width, 

M22 = 1 / rect.Height, 

OffsetX = -rect.Left / rect.Width, 

OffsetY = -rect.Top / rect.Height ， 

M44 = 1 

}； 

// Affine transform: Maps 
// (0 ， 0) --> ptUL 

// (1, 0) --> ptUR 

// (0, 1) --> ptLL 

// (1 ， 1) --> (x2 + xl + xO, y2 + yl + yO) 

Matrix3D A = new Matrix3D() 

{ 

OffsetX = ptUL.X, 

OffsetY = ptUL.Y ， 

Mil = (ptUR.X - ptUL.X), 

M12 = (ptUR.Y - ptUL.Y), 

M21 = (ptLL.X - ptUL.X), 

M22 = (ptLL.Y - ptUL.Y), 

M44 = 1 


}； 


// Non-affine transform 
Matrix3D B = new Matri x3D() ; 

double den = A.Mil * A.M22 - A.M12 * A.M21; 
double a = (A.M22 * ptLR.X - A.M21 * ptLR.Y + 

A.M21 * A.OffsetY - A.M22 * A.OffsetX) / den; 
double b = (A.Mil * ptLR.Y - A.M12 * ptLR.X + 

A.M12 * A.OffsetX - A.Mil * A.OffsetY) / den; 

B.M11 = a / (a + b - 1); 

B.M22 = b / (a + b - 1); 

B.M14 = B.M11 - 1; 

B.M24 = B.M22 - 1; 

B.M44 = 1; 

// Product of three transforms 
return S * B * A; 
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Unlike the two-dimensional Matrix structure, the Matrix3D structure implements the multiplication 
operator, which makes array manipulation much easier. 


It is certainly possible to drag one of the thumbs to a position where the image disappears 
because at least one of the angles is concave or the lines cross each other. But under those restrictions 
you can indeed stretch the image to a non-affine shape: 



Obviously, it's a little bit of work to persuade the Windows Runtime to apply a taper transform 
of a desired form, but the work is compensated by the pleasures of distorting photographs to make 
people look funny. 
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CHAPTER 11 

The Three Templates 


T he word "template" generally refers to a kind of pattern or mold used for creating identical or 
similar objects. In the Windows Runtime, a template is a chunk of XAML that Windows uses to 
create a visual tree of elements. This might not seem so astonishing. You’ve seen Windows turning 
XAML into visual trees since the first pages of this book. But templates almost always contain data 
bindings, so a single template can result in many visual trees of somewhat different appearances 
based on the binding sources. For this reason, templates are very often defined as resources so that 
they can be shared and used multiple times. 

The title of this chapter refers to three templates. These correspond to the three classes that derive 
from FromeworkTemplate: 

Object 

DependencyObject 

FromeworkTemplate (non-instantiable) 

DotoTemplote 

ControlTemplate 

ItemsPonelTemplote 

You cannot define a template in code. You must use XAML. And don’t expect to get any 
deeper knowledge of these classes by consulting the Windows Runtime documentation. 

DataTemplate defines just one public method, ControlTemplate defines just one public property, 
and ItemsPonelTemplote defines nothing on its own. Virtually everything connected with the actual 
mechanics of the template classes is internal to the Windows Runtime. 

You use DataTemplate to give a visual appearance to data objects that don’t necessarily have 
intrinsic visuals. I will first demonstrate DotoTemplote in connection with controls that derive from 
ContentControl, and it will initially seem to have limited applicability. But DotoTemplote is essential for 
displaying individual items in collections, which involves controls that derive from ItemsControl. 

You use ControlTemplate to redefine the appearance of standard controls; this is a very powerful 
tool for customizing the visuals of an application. 

ItemsPonelTemplote is much simpler than the other two and plays a role only in classes that derive 
from ItemsControl. 

As might be expected from so versatile a tool, the templates defined as part of a DataTemplate or 
ControlTemplate can be complex. Many programmers cherish the help that Expression Blend brings 
in designing their templates. As usual, however, I will demonstrate here how to create templates 
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"by hand." Even if you end up using Expression Blend, you’ll be in better shape for understanding the 
XAML that Expression Blend generates. 

By the end of this chapter, everything in the StandardStyles.xaml file that Visual Studio generates 
as part of standard projects should be entirely comprehensible. 


Data in a Button 


Several common elements and controls in the Windows Runtime can have visual children. The 
most obvious is Panel, which can support multiple children through its Children property of type 
UlElementCollection. The Border can have one child; its Child property is of type UlElement. When you 
create a custom control from UserControl, you set a visual tree to its Content property, which is also of 
type UlElement. 

Button has a Content property as well, but this Content property is of type Object. Why is that? 

The easy answer is: Because Button derives from ContentCoritrol, and ContentControl defines a 
Content property of type Object: 

Object 

DependencyObject 

UlElement 

FromeworkElem en t 
Control 

ContentControl 

ButtonBase 

Button 


But that’s really not a good answer. 

Most of the time, you do not set the Content property of Button to any old object. Most of the 
time you set the Content property to text, and you probably (and correctly) presume that a TextBlock 
is being created behind the scenes to display that text. 

For fancier buttons, you can set the Content property to anything that derives from UlElement. For 
example, here’s a button with a panel containing a bitmap and formatted text: 

〈Button HorizontalAli gnment="Center"> 

<StackPanel> 

〈Image Source="http://www. charlespetzold.com/pw6/PetzoldJersey.jpg" 

Width="100" /> 

<TextBlock> 

<Itali c>Tap</Ital ic> to shoot the basket 
〈 /TextBlock 〉 

</StackPanel> 

</Button> 
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And here it is: 



But if the Content property of Button is truly of type Object, we should be able to set it to 
something that does not derive from UlElement. What do you suppose happens in that case? Try it 
out by setting the content of a button to a LineorGrodientBrush, for example: 

〈Button HorizontalAli gnment="Center"> 

<LinearGradientBrush> 

<GradientStop 0ffset="0" Color="Red" /> 

<GradientStop Offset="l" Color="Blue" /> 

</LinearGradientBrush> 

</Button> 


That's perfectly legal, even though it’s not quite clear what youYe trying to do. Brushes are 
commonly set to various properties of elements (such as the Background or Foreground properties of 
Button) to color them in various ways. But a brush doesn't have any visual representation of its own. 
For that reason what you’ll see displayed in the button is the ToString representation of the brush. 
ToString might return something meaningful for some classes but the default implementation simply 
returns the fully qualified class name: 


Windows.UI.Xaml.Media.LinearGradientBrush 


This is not very satisfying. 

This problem is fixable! ContentCoritrol defines (and Button inherits) not only a Content property 
but also a property named Con ten tTem plate. You set the ContentTemplate property to an object of 
type DotoTemplote, in which you define a visual tree. This visual tree usually contains bindings that 
reference the object set to the Content property. 

Let’s first add property-element tags for the ContentTemplate property of Button and set to that a 
DotoTemplate: 

〈Button HorizontalAli gnment="Center"> 

<LinearGradientBrush> 

<GradientStop 0ffset="0" Color="Red" /> 

<GradientStop Offset="l" Color="Blue" /> 

</LinearGradientBrush> 
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<Button.ContentTemplate> 
<DataTemplate> 


</DataTemplate> 
</Button.ContentTempl ate> 
</Button> 


Within those DataTemplate tags we can define a visual tree of elements that make use of the 
button content in some way. Let's try an Ellipse: 

〈Button HorizontalAli gnment="Center"> 

<LinearGradientBrush> 

<GradientStop 0ffset="0" Color="Red" /> 

<GradientStop Offset="l" Color="Blue" /> 

</LinearGradientBrush> 


<Button.ContentTemplate> 

<DataTemplate> 

〈Ellipse Width="120" 

Hei ght="144" 
Fill="{Binding}" /> 
</DataTemplate> 

</Button.ContentTempl ate> 

</Button> 


Notice the Binding markup extension on the Fill property of the Ellipse. This is obviously a very 
simple binding. It doesn’t need a Source because the Data Context of this template has been set to the 
content of the button. The binding doesn't have a Path because we want the Fill property set directly 
to the content of the button. The template makes the button content visible: 



Visually, it’s the same as setting an Ellipse as content of the button and defining the 
LinearGrodientBrush directly on the Fill property, like so: 

〈Button HorizontalAli gnment="Center"> 

〈Ellipse Width="120" 

Hei ght="144"> 

<Ellipse.Fill> 

<LinearGradientBrush> 

<GradientStop 0ffset="0" Color="Red" /> 
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<GradientStop Offset="l" Color="Blue" /> 
</LinearGradientBrush> 

</El1ipse.Fill 〉 

</El1ipse> 

</Button> 


However, the template could be part of a style that is shared among multiple buttons, so the template 
approach is definitely more flexible and versatile. 

The data bindings in a DotaTemplote need not be as simple as the one I just showed you. Here’s a 
more extensive template that references the Color property of the second GradientStop object in the 
button’s content and uses that to set the color of a SolidColorBrush that strokes the circumference of 
the ellipse: 

〈Button HorizontalAli gnment="Center"> 

<LinearGradientBrush> 

〈GradientStop 0ffset="0" Color="Red" /> 

〈GradientStop Offset="l" Color="Blue" /> 

</LinearGradientBrush> 

<Button.ContentTemplate> 

<DataTemplate> 

〈Ellipse Width="120" 

Hei ght="144" 

Fill="{Binding}" 

StrokeThi ckness="6"> 

<E11ipse.Stroke> 

〈SolidColorBrush Color="{Bi nding Path=Gradi entStops[1].Color}" /> 

</El1ipse.Stroke> 

</El1ipse> 

</DataTemplate> 

</Button.ContentTemplate> 

</Button> 


The Binding on the Color property of the SolidColorBrush uses a Path to reference the 
GrocJientStops property of the UriearGradieritBmsh, dr\ index to obtain a particular GradientStop 
object, and then Color to get a property of that object: 

〈SolidColorBrush Color="{Bi nding Path=Gradi entStops[1].Color}" /> 

A Binding in a DatoTemplate usually doesn't have an ElementName or Source setting because that 
source is provided as the data context. Because Path is the first (and only) item in the Binding, the 
"Path=" part can be removed: 

〈SolidColorBrush Color="{Bi nding GradientStops [1].Color}" /> 
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This is how you’ll almost always see bindings in data templates, and here’s what results: 



Of course, the template is relying on the content being a LineorGradientBrush. If it’s not, the 
bindings won’t work. 

You can define a DatoTemplote in the Resources section of a page (or other XAML file): 


<Page.Resources 〉 

<DataTemplate x:Key="el 1ipseTemplate"> 

〈Ellipse Wi dth="120" 

Height="144" 

Fill="{Binding} M 
StrokeThi ckness="6"> 

<E11ipse.Stroke> 

<SolidColorBrush Color="{Bi nding GradientStops[l] .Color}" /> 

</El1ipse.Stroke> 

</El1ipse> 

</DataTemplate> 

</Page.Resources 〉 

Referencing this template in a button requires only the standard StaticResource markup extension: 

<Button HorizontalAli gnment="Center" 

ContentTemplate="{Stati cResource el 1ipseTemplate}"> 

<LinearGradientBrush> 

<GradientStop 0ffset="0" Color="Red" /> 

<GradientStop Offset="l" Color="Blue" /> 

</LinearGradientBrush> 

</Button> 


The template can be shared among multiple buttons (or other ContentControl derivatives). 
Normally, visual trees cannot be shared because visual elements can’t have more than one parent. But 
the template works quite differently. When a template is shared, it is used to generate a unique visual 
tree for each control that references it. If 100 buttons have their ContentTemplate properties set to 
this template, 100 Ellipse elements will be created. 
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Very often, a template is defined within a Style so that other properties can be applied to the 
control at the same time. The SharedStyleWithDataTemplate project defines an implicit style in the 
Resources section of the page: 


Project: SharedStyleWithDataTemplate | File: MainPage.xaml (excerpt) 

<Page … > 

<Page.Resources 〉 

<Style TargetType="Button"> 

〈Setter Property="Hori zontalAlignment" Val ue="Center" /> 
〈Setter Property="Verti calA1ignment" Val ue="Center" /> 
〈Setter Prope rty="ContentTempl ate"> 

<Setter.Value> 

<DataTemplate> 

〈Ellipse Wi dth="144" 

Height="192" 

Fin=" {Binding}" /> 

</DataTemplate> 

</Setter.Value> 

</Setter> 

</Style> 

</Page.Resources 〉 


<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Crid.ColumnDefini tions> 

<ColumnDefinition Width="*" /> 

<ColumnDefinition Width="*" /> 

<ColumnDefinition Width="*" /> 

</Grid.ColumnDefinitions> 

〈Button Grid.Col umn="0"> 

<SolidColorBrush Color="Green" /> 

</Button> 


〈Button Grid.Column="l"> 

<LinearGradientBrush> 

<GradientStop 0ffset="0" Color="Blue" /> 
<GradientStop Offset="l" Color="Red" /> 
</LinearGradientBrush> 

</Button> 


〈Button Grid.Col umn="2"> 

<ImageBrush ImageSource="http: //www.char!espetzold.com/pw6/PetzoldJersey.jpg" /> 
</Button> 

</Grid> 

</Page> 
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The implicit style sets the properties of each Button automatically, including the ContentTemplate 
property. All that’s left for the individual buttons is to define a Brush derivative as content: 



A template references objects through normal data bindings, so if the source object implements 
a notification mechanism — most likely INotifyPropertyChanged — then the visuals are dynamically 
updated. For example, suppose you create a Clock class that uses a CompositionTorget.Rendering 
event to obtain the current time and use that to set several properties, each of which fires a 
PropertyChonged event: 

Project: ClockButton | File: Clock.cs 

using System; 

using System.ComponentModel; 

using System.Runtime.Compi1erServices; 

using Windows.UI.Xaml.Media; 

namespace ClockButton 

{ 

public cl ass Clock : INotifyPropertyChanged 

{ 

bool isEnabled; 

int hour, minute, second; 

int hourAngle, minuteAngle, secondAngle; 

public event PropertyChangedEventHandler PropertyChanged; 

public bool IsEnabled 

{ 

set 

{ 

if (SetProperty<bool >(ref isEnabled, value, "IsEnabled")) 
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if (isEnabled) 

CompositionTarget .Rendering += OnCompositionTargetRendering; 




el se 

CompositionTarget .Rendering -= OnCompositionTargetRendering; 


get 



return isEnabled; 


public int Hour 

{ 

set { SetProperty<i nt>(ref hour, value); } 
get { return hour; } 

} 


public int Minute 

{ 

set { SetProperty<i nt>(ref minute ， value); } 
get { return minute; } 

} 

public int Second 

{ 

set { SetProperty<i nt>(ref second, value); } 
get { return second; } 

} 


public int HourAngle 

{ 

set { SetProperty<i nt>(ref hourAngle, value); } 
get { return hourAngle; } 

} 


public int MinuteAngle 

{ 

set { SetProperty<i nt>(ref minuteAngle, value); } 
get { return minuteAngle; } 

} 

public int SecondAngle 

{ 

set { SetProperty<i nt>(ref secondAngle, value); } 
get { return secondAngle; } 

} 

void OnCompositionTargetRendering (object sender, object args) 

{ 

DateTime dateTime = DateTime.Now; 

this .Hour = dateTime.Hour; 
this .Minute = dateTime.Minute; 
this .Second = dateTime.Second; 

this .HourAngle = 30 * dateTime.Hour + dateTime.Minute / 2; 

this .MinuteAngle = 6 * dateTime.Minute + dateTime.Second / 10; 

this .SecondAngle = 6 * dateTime.Second + dateTime.Millisecond / 166; 

} 
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protected bool SetProperty<T>(ref T storage, T value, 

[Cal lerMemberName] string propertyName = null) 


{ 


if (object .Equals(storage, value)) 
return false; 


storage = value; 

OnPropertyChanged(propertyName); 
return true; 


} 


} 


protected virtual void OnPropertyChanged (stri ng propertyName) 

{ 

if (PropertyChanged != null) 

PropertyChanged(thi s , new PropertyChangedEventArgs (propertyName)); 

} 


You can then set an instance of this class to the content of a Button and use a DataTemplate to 
define how this object is rendered: 


Project: ClockButton I MainPage.xaml (excerpt) 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
〈Button HorizontalA1i gnment="Center" 

VerticalAli gnment="Center"> 

〈 "local : Clock IsEnabled="True" /> 


<Button.ContentTemplate> 

<DataTemplate> 

〈Grid Width="144" Hei ght="144"> 

<Grid.Resources 〉 

<Style TargetType="Polyl ine"> 

<Setter Property=" Stroke" 

Val ue="{StaticResource ApplicationForegroundThemeBrush}" /> 

</Style> 

</Grid.Resources 〉 


〈Polyline Points="72 80, 72 24" 

StrokeThi ckness="6"> 

<Polyline.RenderTransform> 

<RotateTransform Angle="{Binding HourAngl e}" 

CenterX="72" 

CenterY="72" /> 

</Polyline.RenderTransform> 

</Polyline> 

〈Polyline Points="72 88, 72 12" 

StrokeThi ckness="3"> 

<Polyline.RenderTransform> 

<RotateTransform Angle="{Binding MinuteAngle} 

CenterX= n 72" 

CenterY= n 72" /> 

</Polyline.RenderT ransform> 

</Polyline> 
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〈Polyline Points="72 88, 72 6" 

StrokeThi ckness="l"> 

<Polyline.RenderTransform> 

<RotateTransform Angle="{Binding SecondAngl e} 

CenterX="72" 

CenterY="72" /> 

</Polyline.RenderTransform> 

</Polyline> 

</Grid> 

</DataTemp1ate> 

</Button.ContentTemplate> 

</Button> 

</Grid> 


Notice that I’ve defined an implicit Style for Polyline within the visual tree of the DotoTemplote. 
This applies to all the Polyline elements within that visual tree. These Polyline elements have their 
RenderTronsform properties set to a Rota teTra ns form, the Angle of which is bound to various proper¬ 
ties of the Clock class. Together, these three Polyline elements constitute a primitive clock that tells 
time along with functioning as part of a completely functional Button: 



Keep in mind that the DataTemplate set to the ContentTemplate property of the Button defines 
only the appearance of the button content and not the button’s chrome. The button still has a 
rectangular border, for example, and (in the dark theme) it still assumes a somewhat grayer appear¬ 
ance when the mouse passes over and it displays a white background when it’s clicked. Changing 
those aspects of the button’s appearance requires working with a ControlTemplate object set to the 
button’s Template property, as you’ll see later in this chapter. 


CHAPTER 11 The Three Templates 


459 



Making Decisions 


XAML is not a real programming language because it doesn't have loops and //statements. XAML 
isn’t capable of making decisions, so it cannot contain blocks of markup that are conditionally 
executed. 

But we can always try. 

Let’s expand upon the Clock class in the previous project to make it differentiate between morning 
and afternoon. To do this well derive a new class from Clock with a new property named Hourl2 that 
ranges from 1 through 12. Let’s also give this new class a couple Boolean properties named Is Am 
and IsPm in the hopes that we might use these properties for displaying something a little different 
depending on their values. 

The ConditionalClockButton project contains a link to the Clock.cs file from the ClockButton 
project and defines a TwelveHourClock class that derives from Clock: 

Project: ConditionalClockButton | File: TwelveHourClock.es 

namespace ConditionalClockButton 
{ 

public cl ass TwelveHourClock : ClockButton .Clock 
{ 

// Initialize for Hour value of 0 
int hourl2 = 1; 
bool isAm = true; 
bool isPm = false; 

public int Hourl2 
{ 

set { SetProperty<i nt>(ref hourl2, value); } 
get { return hourl2; } 

} 

public bool IsAm 
{ 

set { SetPrope rty<bool>( ref isAm, value); } 
get { return isAm; } 

} 

public bool IsPm 
{ 

set { SetPrope rty<bool>( ref isPm, value); } 
get { return isPm; } 

} 

protected override void OnPropertyChanged(stri ng propertyName) 

{ 

if (propertyName == "Hour") 

{ 

this.Hourl2 = (this .Hour - 1) % 12 + 1; 
this. IsAm = this. Hour < 12; 
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this.IsPm = Ithis.IsAm; 


base .OnPropertyChanged(propertyName) 


} 


Fortunately, I defined the OnPropertyChanged method in Clock as virtual, so this new class can 
override that method and check if the propertyNome argument equals "Hour." If so, all three new 
properties are set, and those properties also call Set Property and hence OnPropertyChanged to fire 
their own PropertyChanged events. 

Suppose you want a Button that says, "It's after 9 in the morning" or "It's after 3 in the afternoon .〃 
This TwelveHourClock class has all the information you need, and you might begin defining the button 
like so: 


<Button> 


<local:TwelveHourClock /> 


<Button.ContentTemplate> 

<DataTemplate> 

<StackPanel Orientati on="Hori zontal "> 

<TextBlock Text="It 's after&#x00A0;" /> 
〈TextBlock Text="{Bi nding Hourl2}" /> 
〈TextBlock Text=" o'clock" /> 

<TextBlock Text=" in the morning!” /> 
<TextBlock Text=" in the afternoon!" /> 
</StackPanel> 

</DataTemplate> 

〈 /Button■ContentTemplate> 

</Button> 


However, one of those two last TextBlock elements needs to be suppressed. The first of that pair 
should be displayed only when the Is Am property is true, and the second should be displayed only 
when Is Pm is true. As you’ll recall, elements have a Visibility property that can be set to members of 
the Visibility enumeration, either Visible or Collapsed. If there were some way to convert the Boolean 
properties of TwelveHourClock to members of the Visibility enumeration, we’d be in great shape. 

I introduced binding converters in Chapter 4, "Presentation with Panels," and it turns out that one 
of the most popular binding converters is often named BooleanToVisibilityConverter. Indeed, if you 
create a project of type Grid App or Split App in Visual Studio, you get one of these converters for 
free in the Common folder, but writing one isn’t hard: 


Project: ConditionalClockButton I File: BooleanToVisibilityConverter.es 

using System; 

using Windows.UI.Xaml; 

using Windows.UI.Xaml.Data; 
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namespace Conditional ClockButton 

{ 

public sealed cl ass BooleanToVisibi1ityConverter : IValueConverter 

{ 

public object Convert(object value, Type targetType, object parameter, string language) 

{ 

return (bool)value ? Vi sibi1ity .Vi sible : Visibility. Collapsed; 

} 

public object ConvertBack (object value ， Type targetType, object parameter, string 1ang) 

{ 

return (Vi sibi1i ty)value == Visibility. Visible; 

} 

} 

} 


The version that Visual Studio generates is just a bit more elaborate than this: It checks that the 
value arguments are actually of the types to which they are cast. But if you’re restricting the use of a 
converter to some specific markup, you can relax the type checking. A restricted use is certainly the 
case in this program, in which the converter is instantiated not in the Resources section of the Page 
but in a Resources section within the template: 


Project: ConditionalClockButton | File: MainPage.xaml (excerpt) 

<Grid Background=” {StaticResource ApplicationPageBackgroundThemeBrush}"> 
<Button HorizontalA1i gnment="Center" 

VerticalAli gnment="Center" 

FontSize="24"> 

<local : TwelveHourClock IsEnabl ed="True" /> 


<Button.ContentTemplate> 

<DataTemplate> 

<StackPanel Orientati on="Hori zontal"> 

<StackPanel.Resources 〉 

<1ocal : BooleanToVisibi1ityConverter x : Key="bool eanToVisibi1ity" /> 
</StackPanel.Resources 〉 


<TextBlock 

<TextBlock 

<TextBlock 

〈TextBlock 


Text="It 's after&#x00A0;" /> 

Text="{Binding Hourl2}" /> 

Text=" o'clock" /> 

Text=" in the morning!” 

Vi sibi1i ty="{Binding IsAm, 

Converter={Stati cResource 


booleanToVisibi1i ty}}" /> 


<TextBlock Text=" in the afternoon!" 


Visibility="{Binding IsPm, 

Converter={Stati cResource 


</StackPanel> 
</DataTemplate> 
</Button.ContentTempl ate> 
</Button> 

</Grid> 


booleanToVisibi1 i ty}}" /> 
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The Visibility properties of the last two Text Block items are now bound to the Is Am and IsPm 
properties of TwelveHourClock, and the BooleonToVisibilityConverter determines which one is visible: 



Collection Controls and the Real Use of DataTemplate 

I’ve been demonstrating the use of DataTemplate with a representative class that derives 
from ContentControl, but there aren’t very many of those classes, and to be honest, the use of 
DataTemplate with these classes is not very common. 

The real use of DataTemplate is with controls that derive from ItemsControl, which are controls that 
store a collection of objects, usually of the same type: 

Object 

DependencyObject 

UlElement 

FromeworkElement 

Control 

ItemsControl 

Selector (non-instantiable) 

ComboBox 

FlipView 

ListBox 

ListViewBase (non-instantiable) 

Grid View 
ListView 
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Certainly the most famous of these is ListBox, which has existed in Windows (in one form or 
another) from the very beginning. The archetypal ListBox presents a vertical list of items through 
which a user can scroll and select using the keyboard or mouse. (The modern ListBox is more flex¬ 
ible and allows touch manipulation.) The ComboBox came a little later in Windows and got its name 
because it combined a text-editing field with a drop-down list of items. FlipView is new in Windows 8. 


The Grid View and ListView are rather more sophisticated than the others and I’ll leave those for 
Chapter 12, "Pages and Navigation.” 

When working with these various controls, it's easy to neglect ItemsControl itself, from which 
everything else derives. ItemsControl simply displays a collection of items for presentation purposes; 
there’s no concept of selection. The Selector class adds selection logic, and all the other classes derive 
from that. I’ll generally refer to this entire group of controls as items controls. All of them display a 
collection of items. 

You can get objects into an items control in one of four ways: individually in XAML, individually in 
code, in bulk in code, or in bulk in XAML, usually with a data binding. The objects that you put into 
an items control usually do not derive from UlElement. Very often these items are business objects or 
view models. 

For a brief list of items, you can specify them right in the XAML file: 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

〈ItemsControl FontSize="24"> 

<x: Stri ng>One potato</x : String> 

<x : Stri ng>Two potato</x : String> 

<x: Stri ng>Three potato</x: String> 

<x: Stri ng>Four</x: Stri ng> 

<x: String>Fi ve potato</x: String> 

<x: String>Si x potato</x : String> 

<x : Stri ng>Seven potato</x: String> 

<x: Stri ng>More</x: Stri ng> 

〈 /ItemsControl > 

</Grid> 


The content property of ItemsControl is Items, which is an object of type ItemCollection, a class that 
implements I List, lEnumerable, and lObservableVector. (Ill have more to say about these interfaces 
shortly.) 
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In this example the items being added to the ItemsControl are objects of type String, so they just 
display as text: 


One potato 
Two potato 
Three potato 
Four 

Five potato 
Six potato 
Seven potato 
More 


This particular use of ItemsControl is not much better than a Stack Pan el except that you can fill 
it with items of type String rather than using TextBlock. Behind the scenes, of course, a Text Block is 
generated for each item. 

Unlike the controls that derive from ItemsControl, ItemsControl itself does not have a built-in 
facility for scrolling. It you have a bunch of items that might require scrolling, you’ll want to put the 
ItemsControl inside a Scro I/Viewer, like so: 

<Grid Background:” {StaticResource ApplicationPageBackgroundThemeBrush}"> 

<Scrol1 Viewer> 

〈ItemsControl FontSi ze="24"> 

<Color>Al iceBl ue</Color> 

<Color>Anti queWhi te</Color> 

<Color>Aqua</Color> 

<Color>WhiteSmoke</Color> 

<Color>Yellow</Color> 

<Color>YellowGreen</Color> 

</ItemsControl > 

</Scrol1 Viewer> 

</Grid> 
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This list scrolls, but it's not exactly informative because each Color item is displayed with its 
ToString representation: 


ndows.Foundation.lReference'l <Windows.UI.Color> 


indows.Foundation. 
indows.Foundation. 
indows.Foundation. 
indows.Foundation. 
indows.Foundation. 
indows.Foundation. 
indows.Foundation. 
indows.Foundation. 
indows.Foundation. 
indows.Foundation. 
indows.Foundation. 
indows.Foundation. 
indows.Foundation. 
indows.Foundation. 
indows.Foundation. 
indows.Foundation. 
indows.Foundation. 
indows.Foundation. 
indows.Foundation. 
indows.Foundation. 
indows.Foundation. 
indows.Foundation. 
indows.Foundation. 
indows.Foundation. 
indows.Foundation. 


Reference'1 <Windows.UI.Color> 
Reference'1 <Windows.UI.Color> 
Reference'1 <Windows.UI.Color> 
Reference'1 <Windows.UI.Color> 
Reference'1 <Windows.UI.Color> 
Reference'1 <Windows.UI.Color> 
Reference'1 <Windows.UI.Color> 
Reference'1 <Windows.UI.Color> 
Reference'1 <Windows.UI.Color> 
Reference'1 <Windows.UI.Color> 
Reference'1 <Windows.UI.Color> 
Reference'1 <Windows.UI.Color> 
Reference'1 <Windows.UI.Color> 
Reference'1 <Windows.UI.Color> 
Reference'1 <Windows.UI.Color> 
Reference'1 <Windows.UI.Color> 
Reference'1 <Windows.UI.Color> 
Reference'1 <Windows.UI.Color> 
Reference'1 <Windows.UI.Color> 
Reference'1 <Windows.UI.Color> 
Reference'1 <Windows.UI.Color> 
Reference'1 <Windows.UI.Color> 
Reference'1 <Windows.UI.Color> 
Reference'1 <Windows.UI.Color> 
Reference'1 <Windows.UI.Color> 


Whenever you see a list of type names in an items control, don't fret! You should actually be 
quite happy to see a binding working because it means that you can display these items better. All 
you need do is set the ItemTemplote property of ItemsControl to a DataTemplate with bindings for 
rendering these items: 

<Grid Background=" {StaticResource ApplicationPageBackgroundThemeBrush}"> 

〈 ScrollViewer> 

<ItemsControl > 

<ItemsControl.ItemTemplate> 

<DataTemplate> 

〈Rectangle Wi dth="144" 

Height="72" 

Margin="12"> 

<Rectangle.Fi11 > 

<SolidColorBrush Col or="{Binding}" /> 

</Rectangle.Fi11 > 

</Rectangle> 

</DataTemplate> 

</ItemsControl.ItemTemplate> 

<Color>Al i ceBlue</Color> 

<Color>Anti queWhi te</Color> 

<Color>Aqua</Color> 

<Color>WhiteSmoke</Color> 

<Color>Yellow</Color> 

<Color>YellowGreen</Color> 

</ItemsControl > 

</ScrollViewer> 

</Grid> 
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The ItemTemplate property of ItemsControl is analogous to the ContentTemplote property of 
ContentControl. Both properties are of type DatoTemplote. With the ItemTemplate property, however, 
the template is used to generate a visual tree for each item. Here’s how it looks now: 



As the ItemsControl is being constructed, the DatoTemplote is used to generate 141 Rectangle 
elements and 141 SolidColorBrush objects, one for each item in the control. 

Of course, you probably don’t want a whole list of 141 Color items in the XAML file. You’ll probably 
want to generate them in code. In the Colorltems project, the XAML file contains no items but it does 
have a more elaborate template that also displays the components of the color: 


Project: Colorltems I File: MainPage.xaml (excerpt) 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Scrol1 Viewer> 

<ItemsControl Name="i temsControl" 

FontSi ze="24"> 

〈 ItemsControl.ItemTemplate> 

<DataTemplate> 

〈Grid Width= M 240" 

Margin="0 12"> 

<Grid.ColumnDefinitions> 

<ColumnDefinition Width="144" /> 

<ColumnDefinition Wi dth="Auto" /> 

</Grid.ColumnDefinitions> 

<Grid.RowDefinitions> 

<RowDefinition Height="Auto" /> 

〈RowDefinition Height="Auto" /> 

〈RowDefinition Height="Auto" /> 
<RowDefinition Hei ght="Auto" /> 

</Grid.RowDefiniti ons> 
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〈Rectangle Grid.Col umn="0" 

Grid.Row="0" 

Grid.RowSpan="4" 

Margin="12 0"> 

〈 Rectangle.Fill> 

<SolidColorBrush Color="{Binding}" /> 
</Rectangle.Fi11 > 

</Rectangle> 


<StackPanel Grid.Column="l" 
Gn'd.Row="0" 

Orientati on="Hori zontal"> 
〈TextBlock Text="A =&#x00A0;" /> 
〈TextBlock Text="{Bi nding A}" /> 
</StackPanel> 


<StackPanel Grid.Column="l" 
Grid.Row="l" 

Orientati on="Hori zontal"> 
<TextBlock Text="R =&#x00A0;" /> 
<TextBlock Text="{Bi nding R}" /> 
</StackPanel> 


<StackPanel Grid.Column="l" 
Gn'd.Row= M 2" 

Orientati on="Hori zontal"> 
<TextBlock Text="G =&#x00A0;" /> 
<TextBlock Text="{Bi ndi ng G}__ /> 
</StackPanel > 

<StackPanel Grid.Column="l" 
Grid.Row="B" 

Orientati on="Hori zontal"> 
〈TextBlock Text="B =&#x00A0;" /> 
<TextBlock Text="{Bi nding B}" /> 
</StackPanel > 

</Grid> 

</DataTemplate> 

</ItemsControl.ItemTemplate> 

</ItemsControl > 

</ScrollViewer> 

</Crid> 


The items themselves are generated in code. As you probably expect by now, the code-behind file 
uses reflection to obtain all the Color properties defined by the static Colors class. Each Color value 
is added to the ItemsControl using the Add method defined by ItemCollection. This represents the 
second method of putting items in an items control: 


Project: Colorltems | File: MainPage.xaml (excerpt) 

public MainPageO 

{ 

this .InitializeComponentC); 
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IEnumerable<PropertyInfo> properties = typeof (Colors) .GetTypelnfoC).DeclaredProperties; 


foreach (Propertylnfo property in properties) 

{ 

Color clr = (Colo r)property.GetValue (null) ; 
itemsControl.Items.Add(clr); 


And now we get the color display with the decimal values of the components of each color: 



Unfortunately, we can’t use this same technique to display the name of each color because that’s 
not part of the Color structure. If we want to display the name along with the color, well need to fill 
the ItemsControl with instances of a class that provides this name. 


Let’s create this class. In a library project I’ve called Petzold.ProgrammingWindows6.Chapterll, I’ve 
defined a class called NomedColor: 


Project: Petzold.ProgrammingWindows6.Chapterll | File: NamedColor.es (excerpt) 

public cl ass NamedColor 

{ 

static NamedColorC) 

{ 

List<NamedCol or> colorList = new List<NamedCol or>() ; 

IEnumerable<PropertyInfo> properties = typeof (Colors) .GetTypelnfoC).DeclaredProperties; 


foreach (Propertylnfo property in properties) 

{ 

NamedColor namedColor = new NamedColor 

{ 

Name = property.Name, 

Color = (Col or) property.GetValue (nul 1 ) 

}； 
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} 


col orList.Add(namedColor); 


All = colorList; 

} 

public static IEnumerable<NamedColor> All { private set; get; } 
public string Name { private set ; get; } 
public Color Color { private set; get; } 

} 

The NamedColor class has two public properties: a Name property of type string, and a Color 
property of type Color. It also defines a static property named All of type IEnumeroble<NomedColor>. 
This property is set from the static constructor to consist of a collection of all NamedColor objects 
obtained using reflection of the static Colors class. 

I have not defined this class as implementing I Notify PropertyChanged because the properties of 
any NamedColor object do not change after the object is initialized. 

For displaying hexadecimal color values, the Petzold.ProgrammingWindows6.Chapterll library 
also contains a ByteToHexStringConverter: 


Project: Petzold.ProgrammingWindows6.Chapterll | File: ByteToHexStringConverter.es 
using System; 

using Windows.UI.Xaml.Data; 

namespace Petzold.ProgrammingWindows6.Chapterll 
{ 

public cl ass ByteToHexStringConverter : IValueConverter 
{ 

public object Convert(object value, Type targetType, object parameter, string language) 
{ 

return ((byte)val ue).ToStri ng("X2") ; 

} 

public object ConvertBack (object value ， Type targetType, object parameter, string 1ang) 
{ 

return value; 

} 



As with many of the projects in the rest of this chapter, the ColorltemsSource solution contains 
a link to this library project: With the ColorltemsSource solution in Visual Studio, I right-clicked the 
solution name in the Solution Explorer and chose Add and Existing Project. Then I navigated to the 
Petzold.ProgrammingWindows6.Chapterll.csproj file. I then defined a reference to this project: I 
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right-clicked the References under the ColorltemsSource project and in the Reference Manager dialog 
box I selected Projects (under Solution) at the left and the library at the right. The MainPage.xaml file 
contains an XML namespace declaration for the library: 

xml ns : chll="usi ng : Petzold. Programmi ngWi ndows6 .Chapter'll" 

The MainPage.xaml.es file contains a using directive for this namespace: 

using Petzold. Programmi ngWi ndows6.Chapter'll; 

This project is called ColorltemsSource for a reason: I’ve already shown you how to fill up an 
ItemCollection object accessible from the Items property of ItemsControl from either XAML or code. 
An alternative is the ItemsSource property. This property is defined as type object but you’ll undoubt¬ 
edly set ItemsSource to something that implements the lEnumerable interface. The object you set to 
ItemsSource becomes the collection for the ItemsControl, at which point the Items property becomes 
read-only. 

You can set the ItemsSource property from either code or XAML. Let me show you the code 
approach first. Here’s the XAML file, the bulk of which is a DotoTemplate defining the visual tree for 
each NomedColor item in the collection. 

Project: ColorltemsSource I File: MainPage.xaml (excerpt) 

<Page 

xml ns : chll="usi ng : Petzold. Programmi ngWi ndows6.Chapter'll" 

... > 

<Page.Resources 〉 

<chll:ByteToHexStringConverter x : Key="byteToHexStri ng" /> 

</Page.Resources 〉 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

<ScrollViewer> 

<ItemsControl Name="i temsControl"> 


<ItemsControl.ItemTemplate> 

<DataTemplate> 

<Border BorderBrush="{Stati cResource ApplicationForegroundThemeBrush}" 
BorderThickness="l" 

Width="336" 

Margin="6"> 

<Grid> 

<Grid.ColumnDefinitions> 

<ColumnDefinition Wi dth="Auto" /> 

<ColumnDefinition Wi dth="*"/> 

</Grid.ColumnDefinitions> 

<Rectang1e Grid.Col umn="0" 

Height="72" 

Width="72" 

Margi n="6"> 

<Rectangle.Fill> 

<SolidColorBrush Color="{Bi nding Color}" /> 

</Rectangle.Fill> 

</Rectangle> 
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<StackPanel Grid.Col umn="l" 

VerticalAl ignment="Center"> 
<TextBlock FontSi ze="24" 

Text="{Binding Name}" /> 


<ContentControl FontSi ze="18"> 

<StackPanel Orientati on="Hori zontal"> 


〈TextBlock Text="{Binding Color. A, 

Converter={Stati cResource byteToHexStri ng}}" /> 
<TextBlock Text:"-” /> 

<TextBlock Text="{Binding Color. R, 

Converter={Stati cResource byteToHexStri ng}}" /> 
<TextBlock Text="-" /> 

<TextBlock Text="{Binding Color. G, 

Converter={Stati cResource byteToHexString}}" /> 
<TextBlock Text="-" /> 

<TextBlock Text="{Binding Color. B, 

Converter={Stati cResource byteToHexStri ng}}" /> 
</StackPanel> 

</ContentControl > 

</StackPanel > 

</Grid> 

</Border> 

</DataTemplate> 

</ItemsControl.ItemTemplate> 

</ItemsControl > 

</ScrollViewer> 


</Gri d> 


</Page> 


Notice the seven TextBlock elements displaying the Color components. These are all within a 
horizontal StackPanel, which is then in a ContentControl. The sole reason for this ContentControl is to 
provide a Fontsize that is inherited by the seven TextBlock elements. An implicit Style would also have 
worked fine. 

The bindings on the SolidColorBrush and TextBlock elements obviously imply that an object of 
type NamedColor is being displayed, but no objects of NomedColor are instantiated in the XAML file. 
Instead, the ItemsSource property of the ItemsControl is set in the constructor of the code-behind file: 


Project: ColorltemsSource | File: MainPage.xaml.es (excerpt) 

public MainPageO 

{ 

this .InitializeComponentC); 
itemsControl.ItemsSource = NamedColor. All; 

} 
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When ItemsSource is set, the ItemsControl generates visual trees for all the items in collection: 



It is also possible to implement a XAML-only solution by binding the ItemsSource property to the 
collection. The ColorltemsSourceWithBinding project is very similar to the ColorltemsSource project 
in that it also uses the Petzold.ProgrammingWindows6.Chapterll library, and it defines the same 
DotoTemplate in the XAML file. But a NamedColor object is instantiated as a resource, and a binding 
to the All property is defined in the ItemsSource property of the ItemsControl: 


Project: ColorltemsSourceWithBinding | File: MainPage.xaml (excerpt) 

<Page 

xml ns : chll="usi ng : Petzold.ProgrammingWindows6.Chapterll" 

... > 

<Page.Resources 〉 

<chll:NamedColor x : Key="namedColor" /> 

<chll:ByteToHexStringConverter x : Key="byteToHexStri ng" /> 
</Page.Resources 〉 


<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

<ScrollViewer> 

<ItemsControl ItemsSource="{Bi nding Source={Stati cResource namedColor} , 

Path=All}"> 

<ItemsControl.ItemTempl ate> 

<DataTemplate> 

</DataTemplate> 

</ItemsControl.ItemTemplate> 

</ItemsControl> 

〈 /ScrollViewer> 

</Grid> 

</Page> 
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If the resource itself were a collection object, ItemsSource could be set to a StoticResource markup 
extension of that resource, but because the collection is accessible only from the All property of 
NomedColor, a Binding markup extension is necessary to reference the NomecJColor object and the All 
property. 

You’ll recall that Chapter 4 has a couple programs that display lists of colors in various ways and 
that I indicated that we’d need to wait for Chapter 11 to see the best way of doing it. This is it. A class 
defines the type of the items you wish to display, and a DotaTemplote on an ItemsControl defines how 
you want these items rendered. 

This is the coming together of collections and bindings and templates, and it represents an 
essential aspect of Windows Runtime programming. 

Collections and Interfaces 


Normally, in constructing a class such as NamecJColor I would have defined the instance constructor 
as protected or private because it doesn't make much sense for an individual NamedColor object to 
be instantiated from outside the class. That would work fine in the ColorltemsSource project but not 
in ColorltemsSourceWithBinding. In this second program, NamedColor needs a public parameterless 
constructor because the class must be instantiated in XAML as a resource. That particular instance of 
NamedColor isn’t otherwise used: It just provides a way to access the static All property in the bind¬ 
ing. In most programs, you'll probably have a view model class that is instantiated once (the so-called 
singleton pattern) and that provides instance properties of particular collections. (I’ll define such a 
class in the next chapter.) 

In NamedColor, I had some choice in defining the type of the All property. I could have defined 
it as what it actually is: a List<NamedColor>. Or I could have gone to the other extreme and 
defined it as object. That’s not a problem. When the ItemsSource property of an items control 
is set, the control itself checks whether the object set to ItemsSource implements lEnumerable. 

That's all it needs to access the actual items in the collection. That’s why I defined the property as 
IEnumerable<NomedColor>. Regardless of how I later change the internals of NomecJColor class, 

I know that property should always implement lEnumerable because it must provide a suitable 
collection source for an items control. 

When you begin looking at the documentation of collections and interfaces, it’s apt to be a bit 
confusing. Programmers working with .NET recognize the IEnumeroble<T> interface defined in the 
System.Collections.Generic namespace. Yet in some contexts this interface is referred to as llterable<T>, 
which is defined in the Windows.Foundotions.Collections namespace. It's the same interface, but C# 
and Visual Basic programmers refer to it as lEnumerable, while C++ programmers use llterable. 

C# and Visual Basic programmers are also accustomed to working with two basic types of 
collections: List<T>, which is an ordered collection of objects of type T, and Dictionary<JKey, 

TValue>, which is an ordered collection of unique non-null keys and corresponding values. C++ 
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programmers, however, know these two basic types of collections under the names vector and map, 
respectively. For that reason, the Windows.Foundotions.Collections namespace includes the interfaces 
IVector<T> and IMop<K, V>, but C# and Visual Basic programmers see these interfaces as IList<T> and 
IDictionary<TKey, TValue>, both defined in System.Collections.Generic. 

If you just remember "a vector is a list; a map is a dictionary," you’ll certainly be less confused. 

You’ve already acquired a familiarity with the INotifyPropertyChonged interface defined in 
System.ComponentModel. (C++ programmers use an interface of the same name but defined 
in Windows.Ul.Xoml.Data.) If an item in a collection that is set to ItemsSource implements the 
INotifyPropertyChonged interface, any change to the properties of those items will be reflected in 
the visual elements bound to those properties. In other words, the bindings in the DotoTemplate can 
respond to property changes. You’ve seen this with the ClockButton project for a single item of type 
Clock. It also works with items in collections, as you’ll see in the next chapter. 

When working with collections and items controls, there is another important interface named 
INotifyCollectionChanged defined in System.Collections.Specialized. This interface defines a 
CollectionChangecJ event that is fired when changes to the collection itself occur — that is, when items 
are added to the collection or removed from the collection, or items are reordered. If the collec¬ 
tion set to the ItemsSource property of an items control implements INotifyCollectionChonged, these 
changes will be perceived by the items control and items will be dynamically added to the display or 
removed from the display. 

For C# programmers, the ObservableCollection<T> class implements INotifyCollection Changed, and 
this is the class to use for this purpose in Windows Runtime programming. 

Tapping and Selecting 

In the ColorltemsSource and ColorltemsSourceWithBinding projects, the visuals of each item are 
defined by a DotoTemplate, but that doesn’t prohibit you from getting input events from the 
individual items. In either ColorltemsSource or ColorltemsSourceWithBinding, give the Border that 
begins the DatoTemplote a non-null background and define a handler for the Tapped event: 

〈Border BorderBrush="{Stati cResource ApplicationForegroundThemeBrush}" 

BorderThi ckness="l" 

Width="336" 

Margin="6" 

Backgrounds" {StaticResource ApplicationPageBackgroundThemeBrush}" 

Tapped="OnItemTapped"> 

This gives each of the 144 Border elements the same Topped handler. In that handler, the sender 
argument is the Border] the OriginalSource property of the event arguments is either that Border 
or another element in the template. Regardless, the DotoContext of that element is the particular 
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NomedColor object associated with that item, which means that you can extract the Co/or value and 
use that to color the background: 

void OnltemTapped (object sender, TappedRoutedEventArgs args) 

{ 

object dataContext = (args.OriginalSource as FrameworkElement). DataContext; 

Color clr = (dataContext as NamedColor) .Col or; 

(thi s .Content as Gri d).Background = new SolidColorBrush(cl r); 

} 

Here’s the result when the Brown item has been tapped: 



Considering that you can easily implement a tap or click interface in an ItemsControl, you might 
wonder why you need controls that derive from Selector, most notably ListBox. 

One simple answer is that tapping is not selecting. When an item in a ListBox is selected, it has a 
different visual appearance. In addition, the selection can be moved from item to item by using the 
keyboard arrow keys. If these aren’t features you need, obviously ItemsControl might be a satisfactory 
solution. 

To indicate the currently selected item, Selector defines three different (but obviously related) 
properties: 

■ Selectedlndex is the index of the selected item within the collection, or -1 if no item is currently 
selected. 

■ Selected Item \s the selected item itself, or null if no item is selected. 
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■ SelectedValue is generally the value of a property of the selected item, as indicated by 
SelectedValuePoth. (More on this shortly.) 

If Selectedlndex is not -1, Selected Item \s the same object obtained from indexing the Items 
property with Selectedlndex. All these properties can be set programmatically or in XAML. When a 
ListBox is first filled with items, its Selectedlndex will be -1 and its Selectedltem will be null until these 
properties are explicitly changed or until the user selects an item with a finger or mouse. 

Selector defines a SelectionChanged event that is fired when the selection changes. The handler 
then obtains the selected item by using one of these properties. 

Selectedltem is backed by a dependency property, which means that it can be the target of a 
data binding, but it’s more commonly used as a binding source. The SimpleListBox project uses 
NomedColor.AII as a binding source for the Items property, but it does not define a template. Instead, 
it uses a somewhat different technique for displaying items: 


Project: SimpleListBox I File: MainPage.xaml (excerpt) 

<Page … > 

<Page.Resources 〉 

<chll : NamedColor x : Key="namedColor" /> 
</Page.Resources 〉 


<Gri d> 

<ListBox Name="l stbox" 

ItemsSource="{Bi nding Source={Stati cResource namedColor} , 

Path=All}" 

Displ ayMemberPath="Name" 

Width="288" 

HorizontalAli gnment="Center" /> 

<Grid.Background 〉 

<SolidColorBrush Color="{Bi nding ElementName=l stbox, 

Path=SelectedItem. Color}" /> 

</Grid.Background 〉 

</Grid> 

</Page> 

The Li st Box incorporates its own ScrollViewer, but it tends to grab as much screen space as possible 
regardless of the settings of HorizontalAlignment and VerticolAlignment. You’ll want to give List Box a 
specific Width, as I’ve done here. As you’ll discover shortly, there are very good reasons why a List Box 
can't determine its own width based on the maximum width of its items. 

Rather than defining a DotoTemplote for displaying the NamedColor items, I’ve set the 
DisployMemberPoth to "Name," which refers to the Name property of the items in the List Box. 

These items are of type NamedColor, and fortunately, NamedColor includes a Nome property. This 
is the property that ListBox uses to display the items. Initially, the SolidColorBrush set to the Grid will 
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reference a default Color value because there is no selected item, but once you select an item, that 
color will form the background of the window: 



This program has a dark theme. The light background of the List Box items and the selection 
highlight represent default behavior for the List Box. You’ll see how to change this highlighting later in 
this chapter. If you experiment with this program, you’ll discover that you can move the selection by 
using the keyboard arrow keys, Page Up and Page Down, and Home and End. 

There’s an alternative way to defining the binding to the selected item. Similar to 
DisplayMemberPoth that you use to indicate the property of the item you want displayed is 
SelectedVoluePoth, which is the name of the property to expose as the SelectedVolue: 


<Cri d> 

<ListBox Name="l stbox" 

ItemsSource="{Bi nding Source={Stati cResource namedColor} , 

Path=All}" 

DisplayMemberPath="Name" 

SelectedVal uePath="Color" 

Width="288" 

HorizontalAli gnment="Center" /> 


<Grid.Background 〉 

<SolidColorBrush Color="{Bi nding ElementName=l stbox, 

Path=Sel ectedValue}" /> 

</Grid.Background 〉 

</Crid> 


The SelectedVoluePath property of the List Box indicates that the Color property of the List Box 
items should be exposed as the SelectedVolue property, so the binding on the SolidColorBrush is 
simplified. 
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It’s easy to confuse Selectedltem and SelectedValue. They are the same if no SelectedValuePath 
property has been set. Otherwise, Selectedltem is an object in the collection, and SelectedValue is a 
property of that object. 

It is more common for ListBox to have its ItemTemplote property set to a DotoTemplote, as this one 
does. I’ve simplified the item template to not show the hexadecimal representation of the color, but 
otherwise it’s the same as the ones you’ve seen already: 

Project: ListBoxWithltemTemplate | File: MainPage.xaml (excerpt) 

<Page … > 

<Page.Resources 〉 

<chll : NamedColor x : Key="namedColor" /> 

</Page.Resources 〉 


<Gri d> 

<ListBox Name="l stbox" 

ItemsSource="{Bi nding Source={Stati cResource namedColor} , 

Path=All}" 

Width="B88"> 

<ListBox.ItemTempl ate> 

<DataTemplate> 

<Border 

BorderBrush="{Bi nding RelativeSource={Rel ativeSource TempiatedParent} , 

Path=Fo reground}" 

BorderThi ckness="l" 

Width="336" 

Margin="6" 

Loaded="OnItemLoaded"> 

<Gri d> 

<Grid.ColumnDefinitions> 

<ColumnDefinition Wi dth="Auto" /> 

<ColumnDefinition Wi dth="*"/> 

</Grid.ColumnDefinitions> 


〈Rectangle Grid.Col umn="0" 

Height="72" 

Width="72" 

Margin="6"> 

〈 Rectangle.Fill> 

<SolidColorBrush Color="{Bi nding Color}" /> 
</Rectangle.Fi11 > 

</Rectangle> 


〈TextBlock Grid.Col umn="l" 
FontSi ze="24" 


</Gri d> 
</Border> 
</DataTemplate> 

</ListBox.ItemTempl ate> 
</ListBox> 


Text="{Binding Name}" 

VerticalAli gnment="Center" /> 


<Grid.Background 〉 

<SolidColorBrush Color="{Binding ElementName=l stbox, 

Path=Sel ectedltem.Color}" /> 
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</Grid.Background 〉 

</Gri d> 

</Page> 

Very early in the item template, you might notice a big difference in how the Border is colored. 

In the programs using ItemsControl, the Border could be colored with a reference to the theme 
foreground brush: 

BorderBrush="{Stati cResource ApplicationForegroundThemeBrush}" 

With a dark theme (which I’ve been using throughout the chapter), that's white. 

However, we have discovered that the ListBox items get a white background by default, which 
means that white brush would disappear against the background. We really want to set it to the 
Foreground property of the ancestor element being templated, and the option of doing that is pro¬ 
vided for with a special binding syntax: 

BorderBrush="{Bi nding RelativeSou rce={RelativeSource TempiatedParent } ， 

Pat h=Fo reground}" 

The only two options for RelotiveSource are Self and TemplatedPorent, and you can't use Self here 
because Border doesn't have a Foreground property. 

What is the TemplatedParent exactly? In this context, it’s a Con ten t Presen ter, which is a class that 
you rarely see unless you’re writing another type of template (a control template) that 111 discuss later 
in this chapter. The TextBlock doesn’t need any binding to obtain the correct color because it simply 
inherits the Foreground property, and both elements are properly flipped in color when the item is 
selected: 


Khaki 


Lavender 


LavenderBlush 



LemonChiffon 


LightBlue 


LightCoral 


ListBox supports multiple selection if you need it. Set the SelectionMode property to Multiple or 
Extended, and use the Selectedltems property for obtaining the selected items. 
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Panels and Virtualizing Panels 


I’ve done something in ListBoxWithltemTemplate that I haven’t often done in this book: I’ve left in a 
bit of debugging code. The sole purpose of this is to give you a firsthand glimpse of something very 
important going on internally within List Box. 

The Border element that surrounds each item defines a handler for the Loaded event: 


〈Border BorderBrush="{Bi nding RelativeSou rce={RelativeSource TempiatedParent } ， 

Path=Fo reground}" 

BorderThi ckness="l" 

Width="336" 

Margin="6" 

Loaded="OnItemLoaded"> 

In the Loaded handler, a call to System.Diagnostics.Debug.WriteLine displays the Name property of 
the NamedColor object set to the loaded element’s DataContext property: 


void OnltemLoaded (object sender, RoutedEventArgs args) 

{ 

System.Diagnostics. Debug. WriteLine("Item Loaded : " + 

((sender as FrameworkElement) .DataContext as NamedCol or) .Name); 


Run this program under the Visual Studio debugger, and watch the Output window. When the 
program first loads, you’ll see only several of these colors and definitely not all 141 of them. On my 
tablet, the 768-pixel-tall screen allows for the display of 6 full items (from AliceBlue through Beige) 
and a half of the next item. The list in the Visual Studio Output window shows that visual trees for 11 
items have been loaded, from AliceBlue to BlueViolet. 

Now start scrolling the list. You might see a few more items in the Output window — I see Brown, 
BurlyWoocJ, and CodetBlue — but then the list stops. What exactly is going on? 

The ListBox is being efficient. It's building visual trees only for those items initially displayed (plus a 
couple more), and it’s re-using these visual trees when some items are scrolled out of view and others 
are scrolled into view. And why not? All it needs to do is change the bindings. 

This virtualization is essential when you start binding your ListBox control with collections of 
hundreds or thousands of items. But it also means that ListBox can’t determine the width it needs to 
display all its items. 

Watch out: There might be something peculiar about the items in your collection that have issues 
with this virtualization. I’ll discuss such a case in Chapter 16, "Rich Text,” that involves visual trees 
that contain links to each other. In that case, you can basically turn off this virtualization feature. 

An items control always uses a Panel of some sort to display the items, and you can specify which 
Panel derivative it uses or supply your own. ItemsControl defines (and ListBox inherits) a property 
named ItemsPanel that you can set to an object of type ItemsPonelTemplote. This is the second 
of the three templates referred to in the title of this chapter, but it’s certainly the simplest of the 
three. ItemsPonelTemplote only needs one item: a Panel derivative. This is the panel that the items 
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control uses for hosting the child items. In a regular ItemsControl, it’s a StockPanel. In a ListBox, it’s a 
VirtualizingStockPonel. 


In ListBoxWithltemTemplate, you can set the ItemsPanel property of the List Box to the default 
value with the following markup: 

<ListBox Name="l stbox" 

ItemsSource="{Bi nding Source={Stati cResource namedColor} , 

Path=All}" 

Width="380"> 

<ListBox.ItemTemplate> 

</ListBox.ItemTemplate> 

<ListBox.ItemsPanel > 

<ItemsPanelTemplate> 

<VirtualizingStackPanel /> 

</ItemsPanelTemp1ate> 

</ListBox.ItemsPanel > 

</ListBox> 

Now try changing that to a regular StockPanel: 


<ListBox.ItemsPanel > 

<ItemsPanelTempiate> 
<StackPanel /> 
</ItemsPanelTempiate> 
</ListBox.ItemsPanel > 


Now all the items are created when the List Box is first loaded, as a glance at the Output window in 
Visual Studio will verify. 

However, you can also do this: 


< ListBox■ItemsPanel > 

<ItemsPanelTempiate> 

<VirtualizingStackPanel Orientati on="Hori zontal" /> 
</ItemsPanelTempiate> 

</ListBox.ItemsPanel > 


And that will turn your vertical ListBox into a horizontal ListBox. 

Well, not quite. You’ll also need to make some adjustments to the ListBox size and the internal 
ScrollViewer properties, as I’ve done in the HorizontalListBox project: 

Project: HorizontalListBox I File: MainPage.xaml (excerpt) 

<Page … > 

<Page.Resources 〉 

<chll:NamedColor x : Key="namedColor" /> 

</Page.Resources 〉 

<Gri d> 

〈ListBox Name="l stbox" 
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ItemsSource="{Bi nding Source={Stati cResource namedColor} , 

Path=All} M 

Height="120" 

ScrollVi ewer.HorizontalScrol lMode="Enabl ed" 

ScrollViewer■HorizontalScrol1BarVisibi1i ty="Auto" 

ScrollVi ewer.Vertical Scroll Mode="Di sabled" 

Scrol1Vi ewer.VerticalScrol1BarVisibi1i ty="Di sabled"> 

<ListBox.ItemTemplate> 

<DataTemplate> 

<Border 

BorderBrush="{Bi nding RelativeSou rce={RelativeSource TempiatedParent} , 

Pat h=Foreg round}" 

BorderThi ckness="l" 

Width="336" 

Margin="6" 

Loaded="OnItemLoaded"> 

<Gri d> 

<Grid.ColumnDefinitions> 

<ColumnDefinition Width="Auto" /> 

<ColumnDefinition Wi dth="*"/> 

</Grid.ColumnDefiniti ons> 

〈Rectangle Grid.Column="0" 

Height= M 72 M 

Width="72” 

Margi n="6"> 

〈 Rectangle.Fi11 > 

<SolidColorBrush Color="{Bi nding Color}" /> 

〈 /Rectangle.Fi11 > 

</Rectangle> 


<TextBlock Grid.Col umn="l" 

FontSize="24" 

Text="{Binding Name}" 

VerticalA1i gnment="Center" /> 

</Gri d> 

</Border> 

</DataTemplate> 

</ListBox.ItemTemplate> 

<ListBox.ItemsPanel > 

<ItemsPanelTempiate> 

<VirtualizingStackPanel Orientati on="Hori zontal" /> 
</ItemsPanelTempiate> 

</ListBox.ItemsPanel > 

</ListBox> 


<Grid.Background 〉 

<SolidColorBrush Color="{Bi nding ElementName=l stbox, 

Path=SelectedItem. Color}" /> 

</Grid.Background 〉 

</Grid> 

</Page> 

ScrollViewer defines several properties that govern the control’s appearance and functionality, but 
sometimes the ScrollViewer itself is inaccessible, as it is when it’s inside a List Box. For situations like 
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that, ScrollViewer has conveniently defined several attached properties that you can set right in the 
ListBox tag. 


The only differences between this program and the previous ListBox are the use of a horizontal 
VirtualizingStackPanel and some changes in the ListBox tag to alter the dimensions of the control and 
provide for horizontal scrolling. The result is a fully functional horizontal ListBox: 



Oddly enough, I have not had success using a WropGrid ora VariobleSizedWropGricJ panel with 
ListBox. Attempting to do so raises an exception with the message "The Panel you are using for the 
Control is not allowed as an ItemsPanel for the Control.” But I will provide something similar to these 
wrap panels in the next section. 


Custom Panels 


Perhaps the primary reason to write a custom Panel derivative is to use as an ItemsPanelTemplate of 
an items control. Each type of custom Panel can lay out children in a different manner. 

Writing a Panel derivative that lays out its children in an unusual way — in a circle, perhaps — is 
easiest if all the items can fit on the screen and no scrolling is required. If scrolling is required, the 
layout of the items needs to be conducive to the abilities of ScrollViewer. Or, ScrollViewer itself needs 
to be replaced with some custom scrolling mechanism. 

Panel derivatives can define dependency properties and attached properties. Both Grid and 
Canvas define attached properties, for example. However, generally a Panel derivative that has 
attached properties cannot be used as the ItemsPanelTemplate because there’s usually no sensible 
way to set these attached properties from the DotaTemplate. 
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A Panel derivative always overrides two virtual protected methods: MeosureOverride and 
ArrongeOverride. These correspond to the two passes of layout. During the MeosureOverride method, 
the Panel derivative calls the Measure method on all its children and calculates a desired size for itself. 
During the ArrongeOverride method, the Panel derivative calls Arrange on all its children, which sizes 
and positions each child relative to itself. 

The two method names MeosureOverride and ArrongeOverride might seem somewhat peculiar. 
These method names originated in the Windows Presentation Foundation and involve the difference 
between the WPF versions of the UlElement and FmmeworkElement classes. UlElement implements 
a comparatively simpler layout system involving the methods Measure and Arrange. To the WPF 
UlElement, however, FrameworkElement added the properties Horizontal Alignment, VerticalAlignment, 
and Margin, which make layout considerably more complicated. Hence, FmmeworkElement also 
defines MeosureOverride and ArrongeOverride to supersede the Measure and Arrange methods, 
although Measure and Arrange still continue to play a role in layout. 

In summary, a Panel overrides MeosureOverride and ArrongeOverride and within these meth¬ 
ods calls Measure and Arrange on all its children. Internally, these Measure and Arrange methods 
in the child call the child’s MeasureOverride and ArrongeOverride methods. The child then uses the 
opportunity to call Measure and Arrange on all its children, and the process continues down the tree. 

You can override MeosureOverride and ArrongeOverride in any FrameworkElement derivative, but 
programs written for the Windows Runtime generally do not do so except in Panel derivatives. 

A Panel derivative does not need to bother itself with any of the following properties set on itself 
or its children: 

■ Width, MinWidth, and MoxWidth 

■ Height, Min Height, and MaxHeight 

■ HorizontalAlignment and Vertico I A lign merit 



■ Visibility 

■ Opacity (does not affect layout) 

■ RenderTronsform (does not affect layout) 

All these properties are handled automatically. 

In a Panel derivative, the MeosureOverride method looks like this: 

protected override Size MeasureOverride(Si ze availableSize) 

{ 

return desiredSize; 

} 
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The availobleSize argument is of type Size, which (as you know) has two properties of type double 
named Width and Height. This ovoilobleSize argument is sometimes very simple: If this panel is the 
content of a Page, for example, the availobleSize indicates the size of the page, which is usually the 
size of the application’s window. If this panel is in a cell of a Grid and that Grid cell has specific pixel 
dimensions, the ovoilobleSize is the size of that cell. 

However, there are also common cases where the available size Width or Height or both might 
be infinite. Within the MeosureOverride method, you can test Width and Height for infinity using the 
static Double.IsPositivelnfinity method. 

An infinite Width or Height property of availobleSize means that the parent of the panel is 
offering the panel as much horizontal or vertical space as it needs. If the panel is a child of a vertical 
StackPanel, the Height property will be infinite; if the panel is a child of a horizontal Stack Panel, the 
Width property will be infinite. If the panel is a child of a Canvas, both Width and Height m\\ be infi¬ 
nite. If the panel is in a Grid cell where the cell width and height are both Auto, the Width and Height 
properties of ovoilobleSize will be infinite. 

The MeosureOverride method must properly deal with these cases. The desiredSize returned from 
the method must not have infinite Width or Height properties. In other words, MeosureOverride 
cannot simply return ovoilobleSize. That will not work. 

The MeosureOverride method must call Measure on each of its children; otherwise, the children will 
not be visible. On return from each Measure call, the child’s DesiredSize property will be valid, and the 
panel can use the desired sizes of all its children to compute its own desired size. 

When MeosureOverride calls Measure on a child, it provides an available size for the child. One or 
both properties of this available size can be infinite. For example, a vertical StackPanel calls Measure 
on all its children with an available Width that equals its own available Width and an available Height 
of infinity: 

protected override Size MeasureOverride(Si ze availableSize) 

{ 

double maxWidth = 0; 

double total Height = 0; 

foreach (UIE1ement child in this .Children) 

{ 

child.Measure (new Si ze(avai1ableSize.Width, Double .Positivelnfinity)); 
maxWidth = Math .Max(maxWidth ， child.DesiredSize.Width); 
total Height += chi 1d.DesiredSize.Height; 

} 

return new Si ze(maxWidth, total Height); 

} 

This MeasureOverride for a vertical stack then accumulates a maximum width and a total height of all 
its children. That becomes its desired size. 
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The ArrangeOverride method has an argument that indicates the size computed for this panel. For 
a vertical stack panel, the method again loops through all its children and stacks them, giving to each 
its own width and the child’s desired height: 


protected override Size ArrangeOverride(Si ze final Size) 

{ 

double y = 0; 

foreach (UIE1ement child in this .Children) 

{ 

chi Id.Arrange (new Rect(0, y, finalSize.Width, child.DesiredSize.Height)); 
y += child.DesiredSize.Height; 

} 

return base .ArrangeOverride(finalSize); 

} 

One Panel derivative that I find useful when programming with WPF is called the UniformGrid. 

It’s similar to a regular Grid but every cell has the same size. The children are simply distributed one 
to a cell so that no attached properties are required. Although the size of the children can vary, the 
UniformGrid treats the children as if they all have the same size. This size is based on the maximum 
child size or the space available for the UniformGrid. 

My version of UniformGrid defines two properties named Rows and Columns of type int, but the 
default values are -1, indicating no preset values. If neither of these two properties is set, UniformGrid 
attempts to determine an optimum number of rows and columns; otherwise, if one of the two prop¬ 
erties is set, the other is calculated based on the number of children. It is not recommended that both 
properties be set: If the product of Rows and Columns is less than the number of children, some of the 
children might not appear in the panel. 

In most uses of UniformGrid, Rows and Columns are left at their default -1 values or one or the 
other of these properties is set to 1. If Rows or Columns is set to 1, UniformGrid behaves like a Grid 
with a single column or single row, or like a StockPonel where every child has the same size. 

If the Width and Height properties of ovailobleSize are both finite values, UniformGrid attempts to 
fit all the children into that space. Otherwise, it uses the maximum child size to lay out its children. 

The only situation UniformGrid can't handle is when Rows and Columns are both left at -1 and 
available Width and Height are both infinite. In that case, an exception is raised. 

Like StockPonel, UniformGrid also defines an Orientation property. Here are the property 
definitions and the property-changed handler they all share: 


Project: Petzold.ProgrammingWindows6.Chapterll | File: UniformGrid.es (excerpt) 

public class UniformGrid : Panel 
{ 

// Set by MeasureOverride, used in ArrangeOverride 
protected int rows ， cols; 

static UniformGrid() 
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RowsProperty = DependencyProperty .Regi ster("Rows" , 
typeof (i nt) , 
typeof (Uni formGri d), 

new PropertyMetadata(-l, OnPropertyChanged)); 

ColumnsProperty = DependencyProperty .Regi ster("Col umns" , 
typeof (i nt) , 
typeof (Uni formGri d), 

new PropertyMetadata(-l, OnPropertyChanged)); 

OrientationProperty = DependencyProperty .Regi ster("Ori entation" , 
typeof (Ori entati on) , 
typeof (Uni formGri d), 

new PropertyMetadata(Orientation .Vertical, OnPropertyChanged)); 

} 

public static DependencyProperty RowsProperty { private set ; get; } 

public static DependencyProperty ColumnsProperty { private set; get; } 

public static DependencyProperty OrientationProperty { private set ; get; } 

public int Rows 

{ 

set { SetValue(RowsProperty, value); } 
get { return (i nt)GetVal ue(RowsProperty); } 

} 

public int Columns 

{ 

set { SetValue(ColumnsProperty, value); } 
get { return (i nt)GetVal ue(ColumnsProperty); } 

} 

public Orientation Orientation 

{ 

set { SetValue(OrientationProperty, value); } 

get { return (Ori entati on)GetValue(OrientationProperty); } 

} 

static void OnPropertyChanged(DependencyObject obj, DependencyPropertyChangedEventArgs args) 

{ 

if (args.Property == UniformGrid .OrientationProperty) 

{ 

(obj as UniformGri d) .InvalidateArrange(); 

} 

else 

{ 

(obj as UniformGri d) .InvalidateMeasure(); 

} 
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In the property-changed handler, the InvalidoteMeosure and InvolidateArronge calls signal the 
layout system that a new layout is required. A call to InvalidoteMeosure triggers both measure and 
arrange passes; a call to InvalidoteArronge triggers only an arrange pass, skipping the measure pass. 
In that case, everything remains the same size, but children might be moved to different locations. 

Of course, these are not the only ways that layout is invalidated. Any change in the number of 
children in the panel triggers a new layout, for example. 

The MeosureOverride method begins by performing a couple validity checks and then calculating 
the rows and cols fields by using the Rows and Columns properties and the number of children: 


Project: Petzold.ProgrammingWindows6.Chapterll | File: UniformGrid.es (excerpt) 

protected override Size MeasureOverride(Si ze availableSize) 

{ 

// Only bother if children actually exist 
if (this. Children.Count == 0) 
return new Size() ; 


// Throw exceptions if the properties aren't OK 
if (this. Rows != -1 && this. Rows < 1) 

throw new ArgumentOutOfRangeExcepti on("Uni formGrid Rows must be greater than zero"); 
if (this .Columns != -1 && this .Columns < 1) 

throw new ArgumentOutOfRangeExcepti on("Uni formGrid Columns must be greater than zero") ; 


// Determine the actual number of rows and columns 

// - 

// This option is discouraged 
if (this. Rows != -1 && this. Columns != -1) 

{ 

rows = this. Rows; 
cols = this. Columns; 

} 

// These two options often appear with values of 1 
else if (this .Rows != -1) 

{ 

rows = this. Rows; 

cols = (i nt)Math .Cei1i ng((doubl e)this .ChiIdren.Count / rows); 

} 

else if (this. Columns != -1) 

{ 

cols = this. Columns; 

rows = (i nt) Math .Cei1i ng((doubl e)this .ChiIdren.Count / cols); 

} 

// No values yet if both Rows and Columns are both -1, but 

// check for infinite availableSize 

else if (Double. Islnfinity(avai1ableSize.Width) && 

Double. IslnfinityCavai1ableSize.Height)) 


} 


throw new NotSupportedExcepti on("Compl etely unconstrained Uni formGrid " + 

"requires Rows or Columns property to be set") ; 
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Processing of MeasureOvem.de continues with a calculation of the maximum child size. This is the 
code that enumerates through the Children collection and performs the crucial calls to the Measure 
method of each child. Without this Measure call, the child has zero size. Following the Measure call, 
the DesiredSize property of the child is valid: 


Project: Petzold.ProgrammingWindows6.Chapterll | File: UniformGrid.es (excerpt) 
protected override Size MeasureOverride(Size availableSize) 


// Determine the maximum size of all children 

// - 

Size maximumSize = new Si ze(); 

Size infiniteSize = new Size(Double. Positivelnfinity, 

Double. Positivelnfinity); 

// Find the maximum size of all children 
foreach (UIE1ement child in this .Chi 1dren) 

{ 

child.Measure(infiniteSize); 

Size childSize = chi 1d.DesiredSize; 

maximumSize.Width = Math .Max(maximumSize.Width, childSize.Width); 
maximumSize.Height = Math .Max(maximumSize.Height ， chi 1dSize.Height); 

} 


This is a calculation that occurs in many Panel derivatives. However, the Measure method isn’t 
always called with infinite height and widths. In this particular case, UniformGrid wants to determine 
the "natural size" of each element, and this is the way to do it. 

I mentioned earlier that the Panel derivative does not need to take account of any Margin 
property set on itself or its children. The available size that’s passed as an argument to 
MeasureOverride excludes any Margin property set on the element. However, when the panel calls 
Measure on its children, that size implicitly includes the child’s Margin. The Measure method in 
the child then decreases that available size by the child’s Margin setting. (Of course, if the size is 
infinite, as it is in this case, the result is the same.) That size without the Margin is then passed to 
the child’s MeasureOverride method, and the child calculates a size for itself that it returns from 
MeasureOverride. The child’s Measure method continues by adding the child’s Margin to the size 
returned from MeasureOverride and set’s the child’s DesiredSize property to that increased size. 

This is how Margin is accounted for in layout despite MeasureOverride not bothering with it. 

Now that the maximum child size has been calculated, a desired size for the Panel can be 
calculated. But there is still potentially a rather lengthy calculation: If both Rows and Columns have 
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been left at their default values, the Panel itself needs to calculate an optimum number of rows and 
columns based on available size and the maximum child size: 

Project: Petzold.ProgrammingWindows6.Chapterll | File: UniformGrid.es (excerpt) 
protected override Size MeasureOverride(Si ze availableSize) 


// Find rows and cols if Rows and Colunms are both -1 
if (this. Rows == -1 && this. Columns == -1) 

{ 

if (Double. IslnfinityCavai1ableSize.Width)) 

{ 

rows = (int)Math.Max(l, availableSize.Height / maximumSize.Height); 
cols = (int) Math. Ceiling( (double)this .ChiIdren.Count / rows); 

} 


else if (Double .Islnfinity(avai1ableSize.Hei ght)) 


{ 


col s = 
rows = 

} 

// Neither 
else 
{ 

double 

double 


(i nt)Math .Max(l, availableSize.Width / maximumSize.Width); 
(int) Math. Ceiling( (double)this .ChiIdren.Count / cols); 

dimension is infinite -- the hard one 


aspectRatio = maximumSize.Width / maximumSize.Height; 
bestHeight = 0; 


double bestWidth = 0; 


for (i nt tryRows = 1; tryRows < this .Children.Count; tryRows++) 

{ 

i nt tryCols = (i nt)Math .Cei 1ingC (doubl e) thi s .Chi 1 dren.Count / tryRows); 
double childHeight = availableSize.Height / tryRows; 
double childWidth = availableSize.Width / tryCols; 


// Adjust for aspect ratio 
if (childWidth > aspectRatio * childHeight) 
childWidth = aspectRatio * childHeight; 

else 

childHeight = childWidth / aspectRatio; 


// Check if it's larger than other trials 


if (childHeight > bestHeight) 

{ 

bestHeight = childHeight; 
bestWidth = childWidth; 
rows = tryRows; 
cols = tryCols; 

} 

} 

} 

} 

// Return desired size 

Size desiredSize = new Size(Math .Min(cols * maximumSize.Width, avai1ableSize.Width), 

Math .Min(rows * maximumSize.Height, avai1ableSize.Height)); 


return desiredSize; 


} 
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Normally, the panel's desired size is based entirely on the size of its children and any overhead 
that may be required. That size might well be larger than ovailobleSize. That’s how ScrollViewer knows 
how to scroll a child element. With a non-infinite ovailobleSize on the UniformGrid, however, I want to 
restrict the panel to just that size. 

The ArrongeOverride method is often much simpler than MeasureOverride. The finolSize argument 
is the finite size allocated for the panel. The only requirement for ArrongeOverride is that the Arrange 
method be called on each child, passing to it a Rect object indicating the location of the child relative 
to the panel, and the size of the child. Very often this size is the child’s DesiredSize property, but in 
this case I want the total size of the panel to be allocated equally for the rows and columns: 

Project: Petzold.ProgrammingWindows6.Chapterll | File: UniformGrid.es (excerpt) 

protected override Size ArrangeOverride(Si ze final Size) 

{ 

int index = 0; 

double cellWidth = finalSize.Width / cols; 
double cell Height = finalSize.Height / rows; 

if (this .Orientation == Orientation .Vertical) 

{ 

for (int row = 0; row < rows; row++) 

{ 

double y = row * cell Height; 

for (int col =0; col < cols; col++) 

{ 

double x = col * cellWidth; 
if (index < this .Children.Count) 

this .Children[index] .Arrange(new Rect(x , y, cellWidth, cellHeight)); 
index++; 

} 

} 

} 

else 

{ 

for (int col = 0; col < cols; col++) 

{ 

double x = col * cellWidth; 

for (int row = 0; row < rows; row++) 

{ 

double y = row * cell Height; 
if (index < this .Children.Count) 

this .Children[index].Arrange (new Rect(x , y, cellWidth, cellHeight)); 
index++; 

} 

} 

} 

return base .ArrangeOverride(finalSize); 


492 PART: Elementals 


This is the only place in UniformGrid where Orientation plays a role and governs whether the 
children should be positioned left to right first, or from top to bottom first. The ArrongeOverride 
method almost always returns final Size, which is what the base method returns. 

Let's try this out for a situation where ovoilobleSize has finite Width and Height properties. This is 
the case for an ItemsControl that is not in a ScrollViewer, such as this one: 


Project: AllColorsItemsControl | File: MainPage.xaml (excerpt) 


<Page … > 

<Page.Resources 〉 

<chll : NamedColor x : Key="namedColor" /> 

<chll:ColorToContrastColorConverter x : Key="col orConverter" /> 
</Page.Resources 〉 


<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

<ItemsControl ItemsSource="{Bi nding Source={Stati cResource namedColor} , 

Path=All}"> 

<ItemsControl.ItemTemplate> 

<DataTemplate> 

<Border 

BorderBrush="{Bi nding RelativeSou rce={RelativeSource TempiatedParent} , 

Pat h=Foreg round}" 

BorderThickness="2" 

Margin="2"> 

<Border.Background 〉 

<SolidColorBrush Color="{Binding Color}" /> 

</Border.Background 〉 

<Viewbox> 

<TextBlock Text="{Binding Name}" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Center"> 

<TextBlock.Foreground 〉 

<SolidColorBrush Color="{Bi nding Color, 

Converter={Stati cResource colorConverter}}" /> 
</TextBlock.Foreground 〉 

</TextBlock> 

</Viewbox> 

</Border> 

</DataTemp1ate> 

</ItemsControl.ItemTemplate> 


<ItemsControl.ItemsPanel > 

<ItemsPanelTempiate> 

<chll:UniformGrid /> 

</ItemsPanelTemplate> 

</ItemsControl.ItemsPanel > 

</ItemsControl > 

</Gri d> 

</Page> 

Notice the UniformGrid toward the bottom used as the control’s ItemsPanel. 
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I’ve made the item template a little simpler than previous examples. It now consists of a Border 
with its Background property constructed from a binding to the Color property of NomecJColor, 
and a TextBlock child displaying the name of the color. Notice that the Text Block is inside a View- 
box, so the text size should adapt itself to the available size for the child. Also notice that I’ve bound 
the Foreground of the TextBlock to the Color property but passed through a converter named 
ColorToControstColorConverter. This converter calculates a gray shade corresponding to the input 
color and then selects Colors.Black or Colors. White to contrast: 

Project: Petzold.ProgrammingWindows6.Chapterll | File: ColorToContrastColorConverter.es 

public class ColorToContrastColorConverter : IValueConverter 

{ 

public object Convert(object value, Type targetType, object parameter, string language) 

{ 

Color clr = (Color) value; 

double grayShade = 0.30 * clr.R + 0.59 * clr.G + 0.11 * clr.B; 
return grayShade > 128 ? Colors. Black : Colors. White; 

} 

public object ConvertBack (object value, Type targetType, object parameter, string language) 

{ 

return value; 

} 

} 


This works well for every color except Transparent: 


AliceBlue 

AntiqueWhite 

Aqua 

Aquamarine 

Azure 

Beige 

Bisque 

Black 

BlanchedAlmond 

Blue 

BlueViolet 

Brown 

BurlyWood 

CadetBlue 

Chartreuse 

Chocolate 

Coral 

CornflowerBlue 

Cornsilk 

Crimson 

Cyan 

DarkBlue 

DarkCyan 

DarkGoldenrod 

DarkGray 

DarkGreen 

DarkKhaki 

DarkMagenta 

DarkOliveGreen 

DarkOrange 

DarkOrchid 

DarkRed 

DarkSalmon 

DarkSeaGreen 

DarkSlateBlue 

DarkSlateGray 

DarkTurquoise 

DarkViolet 

DeepPink 

DeepSkyBlue 

DimGray 

DodgerBlue 

Firebrick 

FloralWhite 

ForestGreen 

Fuchsia 

Gainsboro 

GhostWhite 

Gold 

Goldenrod 

Gray 

Green 

Green Yellow 

Honeydew 

HotPink 

IndianRed 

Indigo 

Ivory 

Khaki 

Lavender 

LavenderBlush 

LawnGreen 

LemonChiffon 

LightBlue 

LightCoral 

LightCyan 

LightGoldenrodYellow 

LightGray 

LightGreen 

LightPink 

LightSalmon 

LightSeaGreen 

LightSkyBlue 

LightSlateGray 

LightSteelBlue 

LightYellow 

Lime 

LimeGreen 

Linen 


Maroon 

MediumAquamarine 

MediumBlue 

MediumOrchid 

MediumPurple 

MediumSeaGreen 

MediumSIateBlue 

MediumSpringGreen 

MediumTurquoise 

MediumVioletRed 

MidnightBlue 

MintCream 

MistyRose 

Moccasin 

NavajoWhite 

Navy 

OldLace 

Olive 

OliveDrab 

Orange 

OrangeRed 

Orchid 

PaleGoldenrod 

PaleGreen 

PaleTurquoise 

PaleVioletRed 

PapayaWhip 

PeachPuff 

Peru 

Pink 

Plum 

PowderBlue 

Purple 

Red 

RosyBrown 

RoyalBlue 

SaddleBrown 

Salmon 

SandyBrown 

SeaGreen 

SeaShell 

Sienna 

Silver 


SlateBlue 

SlateGray 

Snow 

SpringGreen 

SteelBlue 

Tan 

Teal 

Thistle 

Tomato 


Turquoise 


Wheat 


WhiteSmoke 

Yellow 

YellowGreen 
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All 141 colors fit within the window, which was the objective here. The cells and text become 
smaller when the program is in a snap view: 



However, if the cells become too small, the visuals break down a bit. 

Now let's try Uniform Grid \r\ a ListBox. I Ve retained the simplified data template, but I've given the 
Border and TextBlock specific sizes: 


Project: ListBoxWithUniformGrid I File: MainPage.xaml (excerpt) 


<Page … > 

<Page.Resources 〉 

<chll : NamedColor x : Key="namedColor" /> 

<chll:ColorToContrastColorConverter x:Key="colorConverter" /> 
</Page.Resources 〉 


<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

<ListBox ItemsSource="{Bi nding Source={Stati cResource namedColor} , 

Path=All}"> 

<ListBox.ItemTemplate> 

<DataTemplate> 

<Border 

BorderBrush="{Bi nding RelativeSou rce={RelativeSource TempiatedParent} , 

Pat h=Foreg round}" 

Width="288" 

Height="72" 

BorderThickness="3" 

Margin="3"> 

<Border.Background 〉 

<SolidColorBrush Color="{Binding Color}" /> 

</Border■Background 〉 

〈TextBlock Text="{Binding Name}" 

FontSize="24" 

HorizontalAli gnment="Center" 
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VerticalAli gnment="Center"> 

<TextBlock.Foreground 〉 

<SolidColorBrush Color="{Bi nding Color, 

Converter={Stati cResource colorConverter}}" /> 
</TextBlock.Foreground 〉 

</TextBlock> 

</Border> 

</DataTemplate> 

</ListBox.ItemTemplate> 

<ListBox.ItemsPanel > 

<ItemsPanelTempiate> 

<chll:UniformGrid /> 

</ItemsPanelTempiate> 

</ListBox.ItemsPanel > 

</ListBox> 

</Gri d> 

</Page> 


In this case, the availobleSize argument to the MeasureOverride method in UniformGrid has an 
infinite Height property for vertical scrolling. UniformGrid calculates a number of columns based 
on the available width and maximum child width. The number of rows is calculated from that. 
UniformGrid has a desired size that is based on its total height, and the panel becomes vertically 
scrollable: 



It’s fairly easy to switch to horizontal scrolling. Simply set the ScrollViewer attached proper¬ 
ties as you saw earlier in the HorizontalListBox project and then set the Orientation property of the 
UniformGrid to Horizontal: 

<ListBox ItemsSource="{Bi nding Source={StaticResource namedColor} , 

Path=All}" 

ScrollVi ewer.HorizontalScrol1Mode:" Enabled” 

ScrollVi ewer.HorizontalScrollBarVisibi1i ty="Auto" 
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ScrollVi ewer.Vertical Scroll Mode= M Di sabled" 

ScrollViewer.Vertical ScrollBarVi sibi 1i ty="Di sabled"> 
<ListBox.ItemTemplate> 

<DataTemp1ate> 

</DataTemplate> 

</ListBox.ItemTemplate> 

<ListBox.ItemsPanel > 

<ItemsPanelTempiate> 

<chll:UniformGrid Orientati on="Hori zontal" /> 
</ItemsPanelTemplate> 

</ListBox.ItemsPanel > 

</ListBox> 


The Horizontal setting of Orientation isn’t strictly required but causes the children to be ordered 
differently, first from top to bottom and then from left to right: 



Chartreuse 


JAImond 


Chocolate 


A/ood 


tBIue 


Cyan 


DarkBlue 


DarkCya 



DarkKhaki 


DarkMagenta 


DarkOliveGreen 



DarkOrange 



DarkSeaGreen 


DarkSlateBlue 


DarkSlateGray 


DarkTurquoise 


DarkViolet 


DeepPink 


DeepSkyBlue 


DimGray 


DodgerBlue 


The Item Template Bar Chart 

One of the great "parlor tricks” with an items control involves creating a bar chart with a minimum of 
fuss. All you really need is a data item containing a numeric property suitable for binding, a Rectangle 
in an ItemTemplate, and a UniformGrid or StackPonel to hold the items. 

The RgbBarChart project demonstrates this technique. This ItemsSource for the ItemsControl is, of 
course, the collection of NamedColor objects. The DatoTemplate is a vertical StockPanel containing 
three Rectangle elements, the Height properties of each bound to the R, G, and B properties of the 
Color property of the items. Normally, this would create a stack of three Rectangle elements that start 
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at the top of the Stock Pan el, and I wanted a more traditional looking stacked bar chart oriented at the 
bottom, so I used a RenderTronsform to flip the bars upside down: 


Project: RgbBarChart I File: MainPage.xaml (excerpt) 

<Page … > 

<Page.Resources 〉 

<chll : NamedColor x : Key="namedColor" /> 
</Page.Resources 〉 


<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<ItemsControl ItemsSource="{Bi nding Source={Stati cResource namedColor} , 

Path=All}"> 

<ItemsContro1.ItemTemplate> 

<DataTemplate> 

<StackPanel Name="stackPanel " 

Height="765" 

RenderTransformOrigi n="0 .5 0.5" 

Marginal 0"> 

<StackPanel.RenderTransform> 

<ScaleTransform ScaleY="-l" /> 

</StackPanel.RenderTransform> 


〈Rectangle Fi1 l="Red" 

Hei ght="{Binding 
〈Rectangle Fi ll="Green" 

Hei ght="{Binding 
〈Rectangle Fi1 1="B1 ue" 

Hei ght="{Binding 


Color. R}" /> 
Color. G}" /> 
Color. B}" /> 


<ToolTipService.ToolTi p> 

〈ToolTip x:Name="toolti p" 

PIacementTarget="{Bi nding El ementName=stackPanel }"> 


<!-- Set DataContext to StackPanel containing items--> 
<Grid DataContext="{Bi nding El ementName=tool tip, 

Path=PlacementTarget}"> 


<!-- Set DataContext to NamedColor --> 
<StackPanel DataContext="{Bi nding DataContext}"> 
<TextBlock Text="{Binding Name}" 

HorizontalAli gnment="Center" /> 
〈StackPanel DataContext="{Bi nding Color}" 

Orientati on="Hori zontal" 


HorizontalAli gnment="Center"> 


<TextBlock Text= 
<TextBlock Text= 
<TextBlock Text= 
<TextBlock Text= 
<TextBlock Text= 
<TextBlock Text= 
</StackPanel> 
</StackPanel > 

</Grid> 

</ToolTip> 

</ToolTipService.ToolTip> 


R=" /> 

{Binding R}" /> 
G=" /> 

{Binding G}" /> 

B=" /> 

{Binding B}" /> 
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</StackPanel> 

</DataTemplate> 

</ItemsControl.ItemTemplate> 

<ItemsControl.ItemsPanel > 

<ItemsPanelTempiate> 

<chll:UniformGrid Rows="l" /> 

</ItemsPanelTemplate> 

</ItemsControl.ItemsPanel > 

</ItemsControl > 

</Grid> 

</Page> 

Of course, bars by themselves can be pretty vague, and one good way to identify them is with 
tooltips invoked when the mouse hovers. That turned out to be rather messier. You can attach a 
tooltip to an element by setting a ToolTipService.ToolTip attached property as a child of the element 
and defining a ToolTip control as a child of that. ToolTip derives from ContentControl. However, this 
ToolTip element is not actually part of the visual tree because it "floats" outside the tree. It doesn’t 
inherit properties through the visual tree, including the all-important DataContext property. I had to 
get at that through the PlacementTarget property of ToolTip. 

Here’s the bar chart showing the relative red, green, and blue components of all 141 colors, and a 
tooltip for one of them showing the color name and RGB values: 



For White, the color components total to 765, just a touch under the 768-pixel height of the 
screen. Of course, these bars can be shortened for smaller screens (or larger values) using a 
RenderTronsform. 
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The FlipView Control 

One of my favorite controls introduced in the Windows Runtime is FlipView, which (like List Box) 
derives from ItemsControl by way of Selector. FlipView displays only one item at a time, and that 
item is the selected item, so it shouldn’t replace List Box for most applications. But it has a nice touch 
interface, and it’s good to keep it in mind for some special purposes. 

Like many of the other projects in this chapter, the FlipViewColors project uses the 
Petzold.ProgrammingWindows.Chapterll library. The Resources section of MainPage.xaml contains 
the usual reference to the NamedColor class but also defines a DatoTemplate and ItemsPanelTemplate 
and then references both of those in a Style definition that also includes the ItemsSource binding. A 
Border and TextBlock have SolidColorBrush definitions with bindings to two FlipView controls: 

Project: FlipViewColors | File: MainPage.xaml (excerpt) 

<Page … > 

<Page.Resources 〉 

<chll:NamedColor x : Key="namedCol or" /> 

<chll:ColorToContrastColorConverter x : Key="col orConverter" /> 

<DataTemplate x: Key="colorTempl ate"> 

〈Border BorderBrush="{Bi nding RelativeSou rce={RelativeSource TempiatedParent } ， 

Path=Fo reground}" 

Width="288" 

Height="72" 

BorderThi ckness="3" 

Margi n="3"> 

<Border.Background 〉 

〈SolidColorBrush Color="{Bi nding Color}" /> 

</Border■Background 〉 

〈TextBlock Text="{Binding Name}" 

FontSize="24" 

HorizontalA1i gnment="Center" 

VerticalAli gnment="Center"> 

<TextBlock.Foreground 〉 

<SolidColorBrush Color="{Binding Color, 

Converter={Stati cResource colorConverter}}" /> 
</TextBlock.Foreground 〉 

</TextBlock> 

</Border> 

</DataTemplate> 


<ItemsPanelTempi ate x : Key=" panelTempi ate"> 
<VirtualizingStackPanel /> 
</ItemsPanelTemp1ate> 


<Style TargetType="Fl ipView"> 

〈Setter Property="Wi dth" Value="300" /> 

〈Setter Property="Hei ght" Value="100" /> 

〈Setter Property=" ItemsSource" Val ue="{Binding Source={Stati cResource namedColor} , 

Path=All} M /> 

〈Setter Property="ItemTempl ate" Val ue="{StaticResource colorTemplate}" /> 

〈Setter Property="ItemsPanel " Val ue="{StaticResource panelTemplate}" /> 
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〈Setter Property="SelectedVal uePath" Val ue="Color" /> 
</Style> 

</Page.Resources 〉 


<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Grid.RowDefini ti ons> 

〈RowDefinition Height="Auto" /> 

〈RowDefinition Height:"*" /> 

</Grid.RowDefini ti ons> 

<Grid.ColumnDefini ti ons> 

<ColumnDefinition Width="*" /> 

<ColumnDefinition Width="*" /> 

</Grid.ColumnDefini ti ons> 

〈Border Grid. Row="0" 

Grid.Col umn="0" 

Grid.ColumnSpan="2" 

BorderThi ckness="12" 

CornerRadi us="48" 

Margin="48" 

Padding="48" 

HorizontalA1i gnment="Center"> 

<Border.Background 〉 

<SolidColorBrush Color="{Bi nding ElementName=f 1ipViewl, 

Path=SelectedVal ue}" /> 

〈 /Border■Background 〉 

<Border.BorderBrush> 

<SolidColorBrush Color="{Bi nding ElementName=f 1ipView2, 

Path=SelectedVal ue}" /> 

〈 /Border■BorderBrush> 


<TextBlock FontFami ly="Times New Roman" 

FontSize="96"> 

The <Ital i c>FlipVi ew</Italic> Control 
<TextBlock.Foreground> 

<SolidColorBrush Color="{Bi nding ElementName=f 1ipView2, 

Path=SelectedValue}" /> 

</TextBlock.Foreground> 

</TextBlock> 

</Border> 


<F1ipView Name="fl ipViewl" 

Grid. Row="l" 

Grid.Col umn="0" /> 

<F1ipView Name="fl ipView2" 

Grid. Row="l" 

Grid.Col umn="l" /> 

</Gri d> 

</Page> 

By default, the ItemsPanelTemplate for FlipView is a VirtuolizingStockPonel like List Box but with a 
horizontal orientation. IVe replaced that with a vertical VirtuolizingStockPonel. Like ListBox, FlipView 
controls tend to sprawl out over the available space, so it’s good to set explicit Height and Width 
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properties. The idea here is that you "dial” the controls to two different colors. The first color controls 
the background of the Border; the second controls the border itself and the text: 



Chapter 16 demonstrates how to use a FlipView control as a simple e-book reader. I got the 
idea because the standard printer dialog uses a FlipView for previewing pages, as is demonstrated 
in Chapter 17, "Share and Print.” In that chapter I also use a FlipView for a control that allows date 
selection. 


The Basic Control Template 

You’ve seen how you can set a Data 丁 emplate to the ContentTemplote property of a ContentControl 
derivative, or to the ItemTemplote of an ItemsControl derivative to format the display of data objects. 

You’ve also seen how you can define an ItemsPonelTemplote to set to the Items Panel of an 
ItemsControl derivative to provide a panel for hosting the items. 

The third type of template is of type ControlTemplote. The Control class defines a Template 
property of type ControlTemplote that allows you to entirely redefine the visuals of the control itself — 
not the content of the control but the part of the control commonly referred to as "chrome." 

The existence of the Template property is probably the most important difference between 
a Control derivative and a mere FrameworkElement derivative. Controls have chrome, and the 
appearance of this chrome is entirely under your control. 

Whenever you think you need a custom control, you should probably ask yourself whether it’s 
truly a new control or simply an existing control with a different appearance. Sometimes you get 
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lucky and discover that you can adapt an existing control simply by using a Style. Other times, 
however, you’ll need a ControlTemplote. 


Like a Style, the ControlTemplote is often defined as a resource so that it can be shared. Like a Style 
as well, the ControlTemplote has a TorgetType, which is the type of the control for which the template 
is designed. The Template property defined by Control is backed by a dependency property, which 
means that the Template property can be set in a Style. This is very common, and here’s what it might 
look like in a Resources section: 

<Style x : Key="buttonStyl e" TargetType=" Button"> 

〈Setter Property="Margi n" Value="12" /> 

〈Setter Property="Templ ate"> 

<Setter.Value> 

〈ControlTempi ate TargetType=" Button"> 

</ControlTempiate> 

</Setter.Value> 

</Setter> 

〈 /Style 〉 


Generally, you’ll want to use Setter objects to set some properties of the control together with 
defining the template. These Setter tags define new default properties for the control, but they can be 
overridden by local property settings for the control that uses this style. 

For purposes of clarity in the next several pages, I’ll be defining a ControlTemplote right on the 
control itself. To demonstrate the basics of control templates, I’m going to redefine the appearance of 
a Button, but it won’t be all that different from the existing Button. 

Here’s a standard Button as it might appear in a visual tree. It has content, an event handler, and 
some common properties: 

〈Button Content="Cl ick me!" 

Cli ck="OnButtonClick" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Center" /> 

Let’s define a new ControlTemplote on this Button by breaking out the Template property as a 
property element: 

<Button Content="Cl ick me!" 

Cli ck="OnButtonClick" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Center"> 

<Button.Template> 

<ControlTemplate TargetType="Button"> 


</ControlTemplate> 
〈 /Button.Tempiate> 
</Button> 
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Notice the TorgetType on the ControlTemplate. Sometimes you can leave this out and the template 
will still work except that it will stop working if the template references a property that is defined by 
the target control and not defined by Control. 

A Button with an empty ControlTemplate can still be instantiated, but it no longer has any visual 
appearance. Because it has no visuals, there is no way for a user to see it, let alone click it. Just to 
make sure that we haven’t caused too much damage, let’s put a temporary TextBlock between those 
ControlTemplate tags: 


<Button Content="Cl ick me!" 

Cli ck="OnButtonClick" 

HornzontalAli gnment="Center" 

VerticalAl ignment="Center"> 

<Button.Template> 

〈ControlTemplate TargetType=" Button"> 
<TextBlock Text=" temporary" /> 
</ControlTemplate> 

</Button.Tempiate> 

</Button> 


Now the Button again has a visual appearance that consists solely of this text, and it is also 
functional. That Click event definitely fires when you tap or click the TextBlock. The visuals, however, 
are static. There is no longer any special appearance to indicate that the mouse pointer is hovering 
over the Button or that the Button is in the process of being clicked. Along with the standard visuals, 
those special appearances are defined within the template. 

You can put a Border around the TextBlock: 


<Button Content="Cl ick me!" 

Cli ck="OnButtonClick" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Center"> 

<Button.Template> 

<ControlTempi ate TargetType="Button"> 
〈Border BorderBrush="Red" 

BorderThi ckness="3"> 
〈TextBlock Text=" temporary" /> 
</Border> 

</ControlTemplate> 

</Button.Tempiate> 

</Button> 
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And here’s what it looks like: 



But do you really want to hard-code a red brush in the template? If you're defining a template for 
a single Button as I’m doing here, that’s fine. But in the general case, you’ll be defining templates as 
shared resources, and sometimes you might want this Border to be red, and other times you might 
want it to be something else. 

Control itself defines BorderBrush and BorderThickness properties, and Button inherits those 
properties, so it would make more sense to define those properties on the Button itself: 

<Button Content="Cl ick me!" 

Cl i ck="OnButtonClick" 

Hori zontalAli gnment="Center" 

VerticalAli gnment="Center" 

BorderBrush="Red" 

BorderThi ckness="3"> 

<Button.Tempiate> 

〈ControlTempi ate TargetType="Button"> 

<Border> 

<TextB1ock Text=" temporary" /> 

</Border> 

〈/ControlTempi ate> 

〈 /Button.Tempiate> 

</Button> 


But now the Border has disappeared entirely from the Button visuals! The Border in the template 
doesn't magically pick up the properties set on the Button. The Border in the template needs some 
kind of binding to reference the properties defined in the Button. 
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This is a very special kind of binding called a TemplateBinding, and it has its own markup extension: 

<Button Content="Cl ick me!" 

Cli ck="OnButtonClick" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Center" 

BorderBrush="Red" 

BorderThi ckness="3"> 

〈 Button.Template 〉 

<ControlTempi ate TargetType="Button"> 

〈Border BorderBrush="{Templ ateBinding BorderBrush}" 

BorderThickness=" {TempiateBinding BorderThickness}"> 

<TextBlock Text=" temporary" /> 

</Border> 

</ControlTemplate> 

</Button.Tempiate> 

</Button> 

What the TemplateBinding does is bind properties of an element in the visual tree of a 
ControlTemplate to properties of the control on which the ControlTemplote is applied. The Button 
visuals now contain a red Border as before. 

The TemplateBinding syntax is exceptionally simple: It always targets a dependency property of an 
element in the visual tree of a ControlTemplote. It always references a property of the control to which 
the template is applied. Nothing else can go in the TemplateBinding markup. The TemplateBinding 
only appears on visual trees in a ControlTemplote. 


TemplateBinding is actually a shortcut for a RelativeSource binding. The following bindings work as 
well, but they’re obviously syntactically messier: 

<Button Content="Cl ick me!" 

Cli ck="OnButtonClick" 

HorizontalAli gnment="Center" 

VerticalAl ignment="Center" 

BorderBrush="Red" 

BorderThi ckness="3"> 

〈 Button.Template 〉 

<ControlTempi ate TargetType="Button"> 

〈Border BorderBrush="{Bi nding RelativeSou rce={RelativeSource TempiatedParent } ， 

Path=BorderBrush}" 

BorderThi ckness="{Binding RelativeSou rce={RelativeSource TempiatedParent} , 

Path=BorderThi ckness}"> 

<TextBlock Text=" temporary" /> 

</Border> 

</ControlTemplate> 

</Button.Tempiate> 

</Button> 

You’ll use this verbose syntax if you ever need to establish a two-way binding in a ControlTemplote. 
TemplateBinding is one-way only and does not allow a Mode setting. 


Now suppose you want this red border to be the default in your new button but you want to allow 
individual buttons to override this default. In that case, you can define this ControlTemplate as part of 
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a Style. Keep in mind that normally this Style would be defined as a resource and shared by multiple 
buttons, but I’m attaching it directly to the button for this exercise: 


〈Button Content="Cl ick me!" 

Cli ck="OnButtonClick" 

HorizontalAli gnment="Center" 

VerticalAl ignment="Center"> 

<Button.Style> 

〈Style TargetType="Button"> 

〈Setter Property=" BorderBrush" Value="Red" /> 

〈Setter Property="BorderThi ckness" Value="3" /> 

〈Setter Property="Templ ate"> 

<Setter.Value> 

〈ControlTempi ate TargetType="Button"> 

<Border BorderBrush="{TemplateBi nding BorderBrush}" 

BorderThickness=" {TempiateBinding BorderThickness}"> 
<TextBlock Text=" temporary" /> 

</Border> 

〈 /ControlTempiate> 

</Setter.Value> 

</Setter> 

</Style> 

</Button.Style> 

</Button> 


Now you can set BorderBrush and BorderThickness properties on the Button itself and these will 
override those set in the Style. Let’s add default Background and Foreground properties to this Style, 
as well as a Font Size to make the text a little larger: 


〈Button Content="Cl ick me!" 

Cli ck="OnButtonClick" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Center"> 

<Button.Style> 

<Style TargetType="Button"> 

〈Setter Property=" Background" Val ue="Whi te" /> 

〈Setter Property=" Foreground" Value="Blue" /> 

〈Setter Property=" BorderBrush" Value="Red" /> 

〈Setter Property="BorderThi ckness" Value="3" /> 

〈Setter Property="FontSi ze" Value="24" /> 

〈Setter Property="Templ ate"> 

<Setter.Value> 

〈ControlTempi ate TargetType="Button"> 

<Border Background=" {TempiateBinding Background}" 

BorderBrush=" {TempiateBinding BorderBrush}" 

BorderThickness=" {TempiateBinding BorderThickness}"> 
<TextBlock Text=" temporary" /> 

</Border> 

〈 /ControlTempiate> 

</Setter.Value> 

</Setter> 

</Style> 

</Button.Style> 

</Button> 
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Notice the TemplateBinding on the Background property of the Border. However, the TextBlock 
doesn’t need a TemplateBinding for the Foreground or Fontsize properties because those properties 
are inherited through the visual tree. The TextBlock now shows up with blue text a little larger than 
before: 



So far, each TemplateBinding has bound a property of an element in the visual tree with a property 
of the same name in the control. This one-to-one equivalence isn’t required. Within the template, you 
could easily swap the bindings of Background and BorderBrush because both are of type Brush. 

<ControlTemplate TargetType="Button"> 

<Border Background="{TemplateBinding BorderBrush}" 

BorderBrush=" {TempiateBinding Background}" 

BorderThickness=” {TempiateBinding BorderThickness}"> 

<TextBlock Text=" temporary" /> 

</Border> 

</ControlTemplate> 


There’s nothing wrong with this except for the bafflement that it might cause. 

Perhaps you want this new Button to have rounded corners on the Border. There’s no property in 
Control or Button that corresponds to that, so unless we want to define a class derived from Button 
that includes a CornerRadius property, well have to hard-code it. Here's only the ControlTemplote 
part of the markup: 

<ControlTemplate TargetType=" Button"> 

<Border Background="{Templ ateBinding Background}" 

BorderBrush=" {TempiateBinding BorderBrush}" 

BorderThickness=" {TempiateBinding BorderThickness}" 

CornerRadi us="12"> 

<TextBlock Text=" temporary" /> 

</Border> 

</ControlTemplate> 
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Here’s what weYe up to so far: 



Let’s address the little issue of the TextBlock with the temporary text. Based on what you’ve seen 
so far, you might be tempted to replace that temporary text with a TemploteBinding to the Content 
property of the Button: 

〈TextBlock Text="{TemplateBinding Content}" /> 

This works in this example, but it is very wrong. I began this chapter by discussing how the Content 
property of a ContentControl derivative such as Button is of type object, and TextBlock only works for 
text. It doesn’t even work when the content is set to a bitmap. 

Fortunately, there is a special class designed expressly to display content inside a ContentControl 
derivative. That class is ContentPresenter, and like ContentControl it has a Content property of type 
object: 

<ControlTemplate TargetType=" Button"> 

〈Border Background="{Templ ateBinding Background}" 

BorderBrush=" {TempiateBinding Borde 「 Brush}" 

BorderThi ckness="{TemplateBinding BorderThickness}" 

CornerRadi us="12"> 

<ContentPresenter Content="{TemplateBinding Content}" /> 

</Border> 

〈 /ControlTemplate 〉 

You’ll find a ContentPreseriter in most every template for ContentControl derivatives. 
ContentPresenter derives from FromeworkEIement, but it also generates its own visual tree to 
render the content. In this specific example, Con ten tPresen ter creates a TextBlock to display its 
Content property. 
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ContentPresenter is also entrusted with the job of building a visual tree to display any kind of 
content based on the ContentTemplate property of the control. Indeed, ContentPresenter has its own 
ContentTemplate property that you can bind to the ContentTemplate property of the control: 

〈ControlTempi ate TargetType="Button"> 

<Border Background="{TemplateBinding Background}" 

BorderBrush=" {TempiateBinding Borde 「 Brush}" 

BorderThickness=" {TempiateBinding BorderThickness}" 

CornerRadi us="12"> 

〈ContentPresenter Content="{Templ ateBinding Content}" 

ContentTemplate="{Templ ateBinding ContentTemplate}" /> 

</Border> 

</ControlTemplate> 


These two template bindings on ContentPresenter are so standard and so essential that they’re not 
actually required! ContentPresenter will automatically pick up the values of these properties from the 
control in which it’s being used. If you want to leave them out, you can do so. I personally feel more 
comfortable seeing them in there. 

You might recall that Control defines a property named Padding that is intended to provide a little 
space between the control’s chrome and the control’s content. Try setting the Podding property in 
this Button: 

<Button Content="Cl ick me!" 

Cli ck= M OnButtonClick" 

HornzontalAli gnment="Center" 

VerticalAli gnment="Center" 

Padding= ,, 24"> 


</Button> 


Nothing happens. You need to add something to the ControlTemplote to explicitly leave a little 
space between the Border and the ContentPresenter. This can be a TemploteBincJing on the Padding 
property of the Border, but the more common approach is to set a TemplateBinding on the Margin 
property of the Con ten tPresen ter: 

<ControlTemplate TargetType="Button"> 

<Border Background="{Templ ateBinding Background}" 

BorderBrush=" {TempiateBinding Borde 「 Brush}" 

BorderThickness=” {TempiateBinding BorderThickness}" 

CornerRadi us="12"> 

〈ContentPresenter Content="{Templ ateBinding Content}" 

ContentTempl ate="{TemplateBinding ContentTempl ate}" 

Margi n="{TemplateBinding Padding}" /> 

</Border> 

〈 /ControlTempiate> 
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Now try setting the HorizontolAlignment and Vertical A lignmen t properties of the Button to Stretch. 
The Button properly expands to fill the page: 



This is good because it means that these properties are being handled automatically. However, 
the content is at the upper-left corner of the button. Control defines two properties named 
HorizontalContentAlignment and VerticolContentAlignment that govern how content should be 
positioned within the button, but if you try setting these properties, you’ll find that they don't work. 


This means you'll have to add something to the template to get them to work. The standard way is 
for these properties to be bound to the HorizontolAlignment and VerticolAlignment properties of the 
Con ten tPresen ter 

<ControlTemplate TargetType=" Button"> 

<Border Background="{TemplateBinding Background}" 

BorderBrush=" {TempiateBinding BorderBrush}" 

BorderThickness=" {TempiateBinding BorderThickness}" 

CornerRadi us="12"> 

<ContentPresenter Content="{Temp1ateBinding Content}" 

ContentTempl ate="{TemplateBinding ContentTempl ate}" 

Margi n="{TemplateBindi ng Padding}" 

HorizontalAli gnment="{TemplateBinding HorizontalContentAlignment}" 
VerticalAlignment=" {TempiateBinding VerticalContentAlignment}" /> 

</Border> 

</Contro1Template> 
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These properties position the ContentPresenter vj\th\r\ its parent, which in this case is the Border. 

I'm going to add one more TemploteBinding on the ContentPresenter and then declare it ready for the 
next step: 


〈Button Content="Cl ick me!" 

Cli ck="OnButtonClick" 

HorizontalAli gnment="Center M 
VerticalAli gnment="Center" 

Padding="24"> 

<Button.ContentTransitions> 

<TransitionCol1ection> 

<EntranceThemeTransition /> 

</TransitionCol1ection> 

</Button.ContentTransitions> 

<Button.Style> 

<Style TargetType="Button"> 

〈Setter Property=" Background" Val ue="Whi te" /> 

〈Setter Property=" Foreground" Val ue="Bl ue" /> 

〈Setter Property=" BorderBrush" Value="Red" /> 

〈Setter Property="BorderThi ckness" Value="3" /> 

〈Setter Property="FontSi ze" Value="24" /> 

〈Setter Property="Templ ate"> 

<Setter.Value> 

〈ControlTempi ate TargetType=" Button"> 

<Border Background="{Templ ateBinding Background}" 

BorderBrush=" {TempiateBinding BorderBrush}" 
BorderThickness="{Templ ateBinding BorderThickness} 
CornerRadi us="12"> 


<ContentPresenter Content="{TemplateBinding Content}" 

ContentTempl ate="{TemplateBinding ContentTemplate} 
Margi n="{TemplateBinding Padding}" 

HorizontalAlignment= 

"{TempiateBinding HorizontalContentAlignment}" 
VerticalAlignment= 

"{TempiateBinding VerticalContentAlignment}" 
ContentTransitions= 

"{TempiateBinding ContentT ransitions}" /> 

</Border> 

〈 /ControlTemplate 〉 

</Setter.Value> 


</Setter> 

</Style> 

</Button.Style> 

</Button> 


The ContentTronsitions property of ContentPresenter is now bound to the ContentTransitions 
property of the Button, and I’ve added an EntranceThemeTransition to the Button to test it out. Now 
when the Button loads, the text slides in from the right. 
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The Visual State Manager 


If you’ve been playing along defining new Button visuals, you might have noted that this Button has 
always remained fully functional in firing Click events when it’s been clicked or tapped. However, 
it has been deficient in providing visual feedback to the user. Normal buttons assume somewhat 
different appearances when they are disabled, or have keyboard input focus, or are in the process of 
being clicked, or when the mouse passes over. 

These different appearances are known as visual states, and you build them right into the template 
by using classes that are part of the Visual State Manager. 

The Button has seven visual states divided into two groups: 

■ CommonStates Normal, PointerOver, Pressed, and Disabled 

■ FocusStates Focused, Unfocused, PointerFocused 

Within each group, the states are mutually exclusive. For example, there is no visual state that applies 
to a disabled button that is also pressed. 

The underlying code for the control is responsible for putting the control into these states with 
calls to VisuolStoteMonoger.GoToStote. These states are always referred to with text names. 

Often these visual states are implemented with additional elements in the visual tree of the 
template; these elements are normally invisible. This invisibility can result from the use of a color that 
matches a background color, a Visibility property of Collapsed, or an Opacity of 0. An animation then 
targets this property to make the element visible. Often these animations have a duration of zero, 
which means they occur instantaneously, but you can stretch out your animations if you wish. 

Be forewarned that accounting for these visual states is certainly the most complex part of 
defining a template. If you will be using a control only in a particular application, you might want to 
cut a few corners. For example, if you know that a control will never be disabled, you don’t need to 
provide a visual state for that. 

In the ControlTemplote IVe been building I'm going to handle the Pressed, Disabled, and Focused 
states and then declare it complete. 

In the standard Button, keyboard input focus is indicated by a dotted line that surrounds the 
button’s border. I’m going to instead make it a dotted line that surrounds the content of the button, 
which means it goes inside the Border along with the Con ten tPresen ter, which means that both this 
dotted line and ContentPreseriter need to go in a single-cell Grid. Here’s the dotted line implemented 
with a Rectangle that has the name "focusRectangle”: 

〈ControlTempi ate TargetType=" Button"> 

〈Border Background="{Templ ateBinding Background}" 

BorderBrush=" {TempiateBinding Borde 「 Brush}" 

BorderThickness=” {TempiateBinding BorderThickness}" 

CornerRadi us="12"> 

<Grid> 
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<ContentPresenter Content="{Templ ateBinding Content}" 

ContentTemplate=" {TempiateBinding ContentTempl ate}" 

Margi n="{TemplateBinding Paddi ng}" 

HorizontalAli gnment="{TemplateBinding HorizontalContentAlignment}" 
VerticalAlignment="{Templ ateBinding VerticalContentAlignment}" 
ContentTransiti ons="{TemplateBinding ContentTransitions}" /> 

<Rectangle Name="focusRectangl e" 

Stroke="{TemplateBinding Foreground}" 

StrokeThickness="l" 

StrokeDashArray="2 2" 

Margi n="4" 

RadiusX="12 M 
RadiusY="12" /> 

</Grid> 

</Border> 

〈 /ControlTempiate> 


And here’s what it looks like now: 



Of course, you don’t want that Rectangle to appear all the time. One way to make it invisible is to 
give it an Opacity of 0: 

〈Rectangle Name="focusRectangl e" 

St roke="{TemplateBinding Foreground}" 

0pacity="0" 

StrokeThi ckness="l" 

StrokeDashArray="2 2" 

Margi n="4" 

RadiusX="12" 

RadiusY="12" /> 

Then, customarily within the root element in the visual tree that makes up the ControlTemplate — in 
this example, right after the start tag for Border — you want a VisualStoteMonager.VisuolStoteGroups 
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section. Within that are VisualStoteGroup tags for each group, and within those, VisuolStote tags for 
each state in that group. All are identified with x:Nome attributes: 


<VisualStateManager.VisualStateGroups> 

<VisualStateGroup x: Name="CommonStates"> 
<VisualState x : Name="Normal "> 

</VisualState> 

<VisualState x: Name="Poi nterOver"> 
</VisualState> 

<VisualState x : Name="Pressed"> 

</VisualState> 

<VisualState x : Name="Di sabled"> 

</VisualState> 

</VisualStateGroup> 

<VisualStateGroup x: Name="FocusedStates"> 
<VisualState x : Name="Unfocused"> 

</VisualState> 

<VisualState x: Name=" Focused"> 

</VisualState> 


<VisualState x : Name="Poi nterFocused"> 

</VisualState> 

</VisualStateGroup> 

</VisualStateManager.VisualStateGroups> 


If the visual part of your basic template is designed for the Normal and Unfocused states, you can 
make those empty tags. And if you don't wish to handle various states, you can make those tags 
empty as well: 


<VisualStateManager.VisualStateGroups> 

<VisualStateGroup x:Name="CommonStates"> 
〈VisualState x:Name="Normal " /> 

<VisualState x : Name="Poi nterOver" /> 

<VisualState x : Name="Pressed"> 

</VisualState> 


<VisualState x : Name="Di sabled"> 

</VisualState> 

</VisualStateGroup> 
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<VisualStateGroup x: Name="FocusedStates"> 
<VisualState x : Name="Unfocused" /> 

<VisualState x:Name=" Focused"> 


</VisualState> 


<VisualState x : Name="Poi nterFocused" /> 
</VisualStateGroup> 

</VisualStateManager.VisualStateGroups> 


But don’t delete them. Within a particular group you should have tags for all the states. Leave one 
out and any transition back to that state won’t occur. 

For the states you want to handle, put a Storyboard between the Visual State tags that contains 
animations that target the elements you’ve supplied for this purpose. For example: 

<VisualStateGroup x: Name="FocusedStates"> 

<VisualState x : Name="Unfocused" /> 

<VisualState x: Name="Focused"> 

<Storyboard> 

<DoubleAnimation Storyboard .TargetName="focusRectangl e" 

Storyboard .TargetProperty="Opaci ty" 

To="l" Duration="0" /> 

</Storyboard> 

</VisualState> 


<VisualState x : Name="Poi nterFocused" /> 

</VisualStateGroup> 

Notice the absence of a From property. You want to indicate only what the value should end up at — 
not what it starts at. 

With this in place, when the underlying control receives input focus, its OnGotFocus method is 
called. The control responds by calling VisualStateMonoger.GoToState with "Focused.” This triggers 
the Storyboard, which sets the target Opacity property to 1. When the underlying control loses input 
focus, it calls VisualStateMonoger.GoToStote with "Unfocused,” which undoes that animation. 

For the disabled state, I want the entire control grayed out, and a good way to do that is to cover 
the entire control with a semi-transparent black rectangle with a Visibility of Collapsed. So, let's put 
the Border in another Grid and add a named Rectangle to that Grid that sits visually on top of the 
Border. In doing this, I’ve also moved the Visual State Manager markup to the outermost Grid: 

<ControlTemplate TargetType="Button"> 

<Gri d> 

<VisualStateManager.VisualStateGroups> 


</VisualStateManager.VisualStateGroups> 

<Border Name="border" … > 

<Gri d> 

<ContentPresenter Name=" contentPresenter" … /> 
〈Rectangle Name="focusRectangl e" … /> 

516 PART Elementals 


</Grid> 

</Border> 

〈Rectangle Name="di sabledRect" 

Vi sibi1i ty="Col 1apsed" 

Fill="Black" 

0pacity="0. 5" /> 

</Gri d> 

</ControlTempiate> 

I’ve also given the Border and ContentPresenter names so that I can reference those in animations. 
For the Disabled state, I’ve defined an animation to make the disabledRect visible, and for the Pressed 
state, I’ve defined two animations to set the background and foreground colors of the control. 

These can be seen in the CustomButtonTemplate project, which has the final style and 
template. Primarily to avoid extremely long line lengths on the printed page, I have defined the 
ControlTemplote as a separate object in the Resources dictionary and referenced that from the Style: 


Project: CustomButtonTemplate | File: MainPage.xaml (excerpt) 

<Page … > 

<Page.Resources 〉 

<ControlTemplate x : Key="buttonTempl ate" TargetType=" Button"> 

<Grid> 

<VisualStateManager.VisualStateGroups> 

<VisualStateGroup x: Name="CommonStates"> 

〈VisualState x: Name="Norma"l " /> 

<VisualState x:Name="Poi nterOver" /> 

<VisualState x : Name="Pressed"> 

<Storyboard> 

<0bj ectAni mati onllsi ngKeyFrames 

Storyboard.TargetName=" border" 
Storyboard.TargetPrope rty=" Background"> 
<DiscreteObjectKeyFrame KeyTime="0" 

Val ue="Li ghtGray" /> 

</Obj ectAni mati onllsi ngKeyFrames> 


<Obj ectAni mati onllsi ngKeyFrames 

Storyboard.TargetName=" contentPresenter" 
Storyboard.TargetPrope rty=" Foreground"> 
<DiscreteObjectKeyFrame KeyTi me="0" 

Val ue="Bl ack" /> 

</Obj ectAni mati onllsi ngKeyFrames 〉 

</Storyboard> 

</VisualState> 


<VisualState x: Name="Di sabled"> 

<Storyboard> 

<Obj ectAni mati onllsi ngKeyFrames 

Storyboard .TargetName="di sabl edRect" 
Storyboard.TargetProperty="Vi sibi 1ity"> 
<DiscreteObjectKeyFrame KeyTi me="0" 

Value="Visible" /> 

</0b j ectAni mati onllsi ngKeyFrames> 

</Storyboard> 
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</VisualState> 
</VisualStateGroup> 


<VisualStateGroup x : Name="FocusedStates"> 

<VisualState x : Name="Unfocused" /> 

<VisualState x : Name="Focused"> 

<Storyboard> 

<DoubleAnimation Storyboard.TargetName=" focusRectangle" 

Storyboard .TargetProperty="Opacity" 
To= M l" Duration= M 0" /> 

</Storyboard> 

</VisualState> 


<VisualState x : Name="Poi nterFocused" /> 
</VisualStateGroup> 

</VisualStateManager.VisualStateGroups> 


<Border Name="border" 

Background="{TemplateBi nding Background}" 

BorderBrush=" {TempiateBinding Borde 「 Brush}" 
BorderThi ckness="{TemplateBinding BorderThickness} 
CornerRadi us="12"> 


<Grid> 

〈Content Presenter Name=" content Presenter' 1 

Content="{Templ ateBinding Content}" 

ContentTempl ate="{TemplateBinding ContentTemplate}" 
Margi n="{TemplateBinding Padding}" 

HorizontalAlignment="{Templ ateBinding HorizontalContentAlignment}" 
VerticalAlignment="{Templ ateBinding VerticalContentAlignment}" 
ContentTransiti ons="{TemplateBinding ContentTransitions}" /> 

〈Rectangle Name="focusRectangl e" 

Stroke="{Templ ateBinding Foreground}" 

0pacity="0" 

StrokeThi ckness="l" 

StrokeDashArray="2 2" 

Margi n="4" 

RadiusX="12" 

RadiusY="12" /> 

</Grid> 

</Border> 

<Rectangle Name="di sabledRect" 

Vi sibi1i ty="Col1 apsed" 

Fill="Black" 

0pacity="0. 5" /> 

</Gri d> 

</ControlTemplate> 


<Style x : Key="buttonStyl e" TargetType="Button"> 
〈Setter Property=" Background" Val ue="Whi te" /> 
〈Setter Property=" Foreground" Value="Blue" /> 
〈Setter Property=" BorderBrush" Value="Red" /> 
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〈Setter Property="BorderThi ckness" Value="3" /> 

〈Setter Property="FontSi ze" Value="24" /> 

〈Setter Property="Paddi ng" Value="12" /> 

〈Setter Property="Templ ate" Val ue="{StaticResource buttonTempl ate}" /> 
</Style> 

</Page.Resources 〉 


<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Grid.ColumnDefi ni ti ons> 

<ColumnDefinition Width="*" /> 

<ColumnDefinition Width="*" /> 

<ColumnDefinition Width="*" /> 

</Grid.ColumnDefini tions> 

<Button Content="Di sable center button" 

Grid.Col umn="0" 

Styl e="{StaticResource buttonStyl e}" 

Cli ck="OnButtonlCl i ck" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Center" /> 

<Button Name="centerButton" 

Content="Center button" 

Grid.Col umn="l" 

Styl e="{StaticResource buttonStyl e}" 

FontSize="48" 

Background="DarkGray" 

Foreground="Red" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Center" /> 

<Button Content="Enabl e center button" 

Grid.Column="2" 

Styl e="{StaticResource buttonStyl e}" 

Cli ck="0nButton3Cl i ck" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Center" /> 

</Gri d> 

</Page> 


The XAML file concludes with three buttons, with the center one getting some local property 
values that override those in the Style. The outer two buttons disable and enable the center button: 


Project: CustomButtonTemplate | File: MainPage.xaml.es (excerpt) 

void OnButtonlCli ck(object sender, RoutedEventArgs args) 

{ 

centerButton.IsEnabled = false; 

} 


void 0nButton3Cli ck(object sender, RoutedEventArgs args) 

{ 

centerButton.IsEnabled = true; 

} 
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In this screen shot, the center button has indeed been disabled and the third button has keyboard 
input focus: 



Using generic.xaml 

Look in the following directory of the machine on which you’ve installed Visual Studio: 

C:\Program Files (x86)\Windows Kits\8.0\lnclude\winrt\xaml\design 

You should see two files there. The shorter one, themeresources.xaml, contains mostly SolidColorBrush 
definitions for the standard colors available to Windows Runtime applications, including the famous 
ApplicotionPogeBackgroundThemeBrush and ApplicationForegroundThemeBrush colors. Entire sets of 
these colors are in three sections: Default (meaning the dark theme), Light, and HighContrast. A user 
can select a high-contrast display from the Ease of Access section in the PC Settings program acces¬ 
sible from the Settings charm. 

The larger file, generic.xaml, contains the same definitions as themeresources.xaml, plus all the 
default Style and ControlTemplote definitions for all the standard controls. 

If you want to become good at designing custom templates for controls, studying the default 
templates in generic.xaml is essential. Within these templates is also (apparently) the only documenta¬ 
tion of the visual states associated with each control, as well as the named parts that I’ll discuss in the 
next section. 

To find the default Style for a particular control, do a search of TargetType =〃 followed by the 
control name. 
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Often the templates reference the brushes defined earlier in generic.xaml, and there are 
special brushes for various visual states. For example, visual state animations in the default Button 
template reference brushes with names such as Button Pressed BockgrouncJThemeBrush and 
ButtonPressedForegroundThemeBrush. The actual colors of these brushes are different based on the 
Light or Dark theme the application has selected or the HighContrast theme that the user might have 
selected. 

These Style definitions for all the standard controls have no key names. They are basically implicit 
styles that are applied to the control when the control is instantiated. Anything the application 
provides is in addition to this implicit style. 

One good way to develop a new template for a control is simply to copy the entire existing Style 
definition from generic.xaml into your own XAML file and then begin making changes. 


Template Parts 


As I guided you through the process of constructing a template for a Button, you were possibly 
wondering how this concept works with more sophisticated controls. Consider the Slider, for example. 
The Slider has moving parts. How does the underlying control reference these parts of the template? 


The underlying code for a control such as Slider assumes that certain elements that comprise the 
template have specific names. During initialization, the control code gets references to these elements 
in an override of the OnApplyTemplote method by calling the GetTemploteChild method with these 
names. The control code can save these element objects as fields, install event handlers on them, and 
alter their properties as the user manipulates the control. 

Unfortunately, these named parts are not yet indicated in any documentation I’ve seen for the 
Windows Runtime. You’ll have to study the default templates in generic.xaml to figure out what they 
are. in many cases, you don’t have to know about each and every one. It is considered proper for 
controls to not raise exceptions if certain pieces of the template are missing. 

To be minimally functional, a Slider template must contain a template for both horizontal and 
vertical orientations. These separate templates are generally of type Grid. Give these names of 
"HorizontalTemplate" and "VerticalTemplate". 

Within each Grid must be a Rectangle that encompasses the full extent of the Slider named 
"HorizontalTrackRect” or "VerticalTrackRect”, a Thumb named "HorizontalThumb” or "VerticalThumb”, 
and a second Rectangle that appears to the left of the Thumb named "HorizontalDecreaseRect” or 
"VerticalDecreaseRect". When the user manipulates the Thumb or clicks or taps anywhere within 
the Slider, the underlying control changes the size of this second rectangle to reflect the value 
of the Slider. 
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Let’s look at a nearly minimally functional Slider template that contains several explicit property 
settings and ignores the TickBor elements that provide optional tick marks. This is a project I call 
BareBonesSlider: 


Project: BareBonesSlider I File: MainPage.xaml (excerpt) 

<Page … > 

<Page.Resources 〉 

cControlTempi ate x : Key="sl ide「Tempi ate" 

TargetType="Sl ider"> 

<Gri d> 

<Grid Name="Hori zontalTemplate" 
Background="Transparent" 
Height="48"> 

<Grid.ColumnDefinitions> 

<ColumnDefinition Wi dth="Auto" /> 
<ColumnDefinition Wi dth="Auto" /> 
<ColumnDefinition Width="*" /> 
</Grid.ColumnDefinitions> 


〈Rectangle Name="Hori zontalTrackRect" 

Grid.Col umn="0" 

Grid.Col umnSpan="3" 

Fin="Blue" 

Margi n="0 12" /> 

<Thumb Name="Hori zontalThumb" 

Grid.Column="l" 

DataContext=" {TempiateBinding Val ue}" 
Width="24" /> 

〈Rectangle Name="Hori zontalDecreaseRect" 

Grid.Col umn="0" 

Fin="Red" 

Margi n="0 12" /> 

</Gri d> 


<Grid Name="Verti calTemplate" 

Vi sibi1i ty="Col 1apsed" 

Background="Transparent" 

Width="48"> 

<Grid.RowDefinitions> 

〈RowDefinition Height="*" /> 
〈RowDefinition Hei ght="Auto" /> 
〈RowDefinition Height="Auto" /> 
</Grid.RowDefinitions> 


〈Rectangle Name="Verti calTrackRect" 
Grid.Row="0" 

Grid■RowSpan="3" 
Fill="Blue" 

Margi n="12 0" /> 
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〈Thumb Name="Verti calThumb" 

Grid• Row="l" 

DataContext=" {TempiateBinding Val ue}" 
Height="24" /> 


<Rectangle Name="Verti calDecreaseRect" 
Gn'd.Row="2" 

Fill="Red" 


</Grid> 
</Gri d> 

</ControlTemplate> 
</Page.Resources> 


Margin="12 0" /> 


<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Grid.RowDefiniti ons> 

<RowDefinition Hei ght="Auto" /> 

< RowDefinition Height="*" /> 

</Grid.RowDefiniti ons> 

〈Slider Grid.Row="0" 

Tempi ate="{StaticResource siiderTemplate}" 

Margin="48" /> 

〈Slider Grid.Row="l" 

Tempi ate="{StaticResource siiderTemplate}" 
Orientation="Vertical " 

Margin="48" /> 

</Grid> 

</Page> 


At the bottom of the XAML file are two Slider controls, one horizontal and one vertical, that reference 
these templates. 

I’ll describe the template for the horizontal Slider; the vertical is structured similarly. 

The total width of the Grid named "HorizontalTemplate” is the width of the Slider control in 
layout. The Grid has three columns. The Rectangle named "HorizontalTrackRect" spans all three 
columns so that Rectangle will always be the width of the Slider itself. The Rectangle named 
"HorizontalDecreaseRect” occupies the first column in the Grid, which has a width of Auto, which has 
the effect of reducing that Rectangle to a zero width. The Thumb occupies the center column in the 
Grid, which also has a width of Auto, which means that this center column is the size of the Thumb. 

The underlying code allows the Thumb to move horizontally only and not past the limits of 
the Slider. As the user manipulates the Thumb or presses or taps anywhere else on the Slider, the 
underlying code sets the Width property of the Horizontal DecreaseRect" element accordingly. For 
the minimum value of the Slider, this Width property is set to zero; for the maximum value, it’s set to 
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the width of the "HorizontalTrackRect” element minus the width of the Thumb. I’ve given sizes and 
margins to these components so that the Thumb is a little larger than the rectangles: 



You’ll notice that the template contains a single TemploteBinding that binds the DotoContext of the 
Thumb to the Value property of the Slider. This is required to get the Slider popup tooltip to display 
the correct value. 

As you manipulate the Thumb in BareBonesSlider, you’ll discover that it becomes a nearly 
transparent black as it is being pressed. Thumb derives from Control and hence can be given its own 
template. This is done in the default Slider template in a Resources section attached to the outermost 
Grid of the template. 

With just a little alteration of the BareBonesSlider program, you can do something fancy. Here’s 
something I call a SpringLoadedSlider: 


Project: SpringLoadedSlider | File: MainPage.xaml (excerpt) 

<Page … > 

<Page.Resources 〉 

<Contro"lTempi ate x : Key="sl i de「Tempi ate" 

TargetType="Sl ider"> 

<Gri d> 

<Grid.Resources 〉 

〈Style TargetType="Path"> 

〈Setter Property="StrokeThi ckness" Val ue="6" /> 
<Setter Property="StrokeLi neJoin" Val ue="Round" /> 
〈Setter Property=" Stretch" Val ue="Fi11 " /> 

</Style> 

</Grid.Resources 〉 
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<Grid Name="Hori zontalTemplate" 

Background="Trans parent" 

Height="48"> 

<Grid.ColumnDefinitions> 

<ColumnDefinition Wi dth="Auto" /> 

<ColumnDefinition Wi dth="Auto" /> 

<ColumnDefinition Width="*" /> 

</Gri d. Col umnDefi. ni ti ons> 

<Rectangle Name="Hori zontalTrackRect" 

Grid.Col umn="0" 

Grid.ColumnSpan="3" 

Fill="Transparent" /> 

<Thumb Name="Hori zontalThumb" 

Grid.Column="l" 

DataContext=" {TempiateBinding Val ue}" 

Width="12" /> 

〈Rectangle Name="Hori zontalDecreaseRect" 

Grid.Col umn="0" 

Fi11 ="Transparent" /> 

<Path Stroke="Red" 

Grid.Col umn="0" 

Width="{Bi nding El ementName=Hori zontalDecreaseRect, 

Path=Wi dth}" 

Data="M 0 0 L 100 100, 200 0, 300 100, 400 0, 

400 100, 300 0, 200 100, 100 0, 0 100 Z" /> 

<Path Stroke="Bl ue" 

Grid.Col umn="2" 

Data="M 0 0 L 100 100, 200 0, 300 100, 400 0, 

400 100, 300 0, 200 100, 100 0, 0 100 Z" /> 

</Grid> 


<Grid Name="Verti calTemplate" 

Vi sibi1i ty="Col 1apsed" 
Background="Trans parent" 
Width="48"> 

<Grid.RowDefinitions> 

<RowDefinition Height="*" /> 

< RowDefinition Hei ght="Auto" /> 
〈RowDefinition Hei ght="Auto" /> 
</Grid.RowDefinitions> 


〈Rectangle Name="Verti calTrackRect" 
Gn'd.Row="0" 

Grid.RowSpan="3" 

Fi11 ="Transparent" /> 
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〈Thumb Name="Verti calThumb" 

Grid.Row="l" 

DataContext=" {TempiateBinding Val ue}" 

Height="12" /> 

〈Rectangle Name="Verti calDecreaseRect" 

Grid.Row= M 2" 

Fill="Transparent" /> 

<Path Stroke="Red" 

Grid_Row ， 2 H 

Hei ght="{Binding El ementName=Verti calDecreaseRect, 

Path=Hei ght}" 

Data="M 0 0 L 100 100, 0 200, 100 300, 0 400, 

100 400, 0 300, 100 200, 0 100, 100 0 Z" /> 

<Path Stroke="Bl ue" 

Grid.Row= M 0" 

Data="M 0 0 L 100 100, 0 200, 100 300, 0 400, 

100 400, 0 300, 100 200, 0 100 ， 100 0 Z" /> 

</Grid> 

</Gri d> 

</ControlTemplate> 

</Page.Resources 〉 


<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Grid.RowDefinitions> 

<RowDefinition Hei ght="Auto" /> 

〈RowDefinition Height:"*" /> 

</Grid.RowDefinitions> 

<S1ider Grid. Row="0" 

Tempi ate="{StaticResource siide 「 Tempiate}" 

Margin="48" /> 

<Slider Grid.Row="l" 

Tempi ate="{StaticResource siiderTemplate}" 

Ori entation="Verti cal" 

Margin="48" /> 


</Gri d> 

</Page> 

The two templates are structured the same, except that the Rectangle elements have all been given 
Fill colors of Transparent. In addition, two Path elements have been added to each template. The first 
Path sits in the first column (for a horizontal Slider) and is colored red. The Width of this Path is bound 
to the Width of the element named "HorizontalDecreaseRect”. The second Path is blue and occupies 
the third column. Each has the same geometry — a crisscrossing lattice — with a Stretch mode of Fill, 
meaning that it will fill the space allowed for it. 
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This gives the appearance of springs on either side of the Thumb: 



The default template for the ProgressBar is rather elaborate because it needs to encompass both 
determinate and indeterminate appearances. However, if you restrict yourself to just the determi¬ 
nate ProgressBar, it becomes very simple: The underlying code changes the width of an element 
named "ProgressBarlndicator" between 0 and the width of an element named "DeterminateRoot”. 
In the default template, "DeterminateRoot” is a Border that contains a left-aligned Rectangle named 
"ProgressBarlndicator”. 

In SpeedometerProgressBar, neither "DeterminateRoot” nor "ProgressBarlndicator" are 
visible, but the Width of "DeterminateRoot” is hard-coded as 180. This means that the Width 
of "ProgressBarlndicator” will range from 0 to 180. A binding from the Width property of 
"ProgressBarlndicator" targets the Angle property of a RotateTronsform, which rotates an arrow 
indicator from 0 through 180 degrees: 


Project: SpeedometerProgressBar | File: MainPage.xaml (excerpt) 

<Page … > 

<Page.Resources 〉 

〈ControlTempi ate x : Key=" progressTemplate" 

TargetType=" ProgressBar"> 

<Gri d> 

<Grid.Resources 〉 

<Style TargetType="Li ne"> 

〈Setter Property=" Stroke" Value="Black" /> 
〈Setter Property="StrokeThi ckness" Value="l" /> 
〈Setter Property="Xl" Value="-85" /> 

〈Setter Property="X2" Value="-95" /> 

</Style> 
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〈Style TargetType="TextBlock"> 

〈Setter Property="FontSi ze" Value="ll" /> 

<Setter Property=" Foreground" Value="Black" /> 
</Style> 

</Grid.Resources 〉 

〈Border Width="270" Hei ght="120" 

BorderBrush=" {TempiateBinding Borde 「 Brush}” 
BorderThi ckness="{TemplateBinding BorderThickness} 
Background="Whi te"> 


<!-- Canvas for positioning graphics --〉 

〈Canvas Wi dth="0" Hei ght="0" 

RenderTransform="l 0010 50" > 

<!-- The required parts of the ProgressBar template --> 
<Border Name="Determi nateRoot" 

Width= n 180__> 

〈Rectangle Name=" ProgressBarlndicator" 

HorizontalAli gnment="Left" /> 

</Border> 


<Line RenderTransform=" 1 
<Line RenderTransform=" 0 
<Line RenderTransform=" 0 
<Line RenderTransform=" 0 
<Line RenderTransform=" 0 
<Line RenderTransform=" 0 
<Line RenderTransform="-0 
<Line RenderTransform="-0 
<Line RenderTransform="-0 
<Line RenderTransform="-0 
<Line RenderTransform="-l 


00 0.00 - 0.00 1.00 0 0 " /> 

95 0.31 -0.31 0.95 0 0" /> 

81 0.59 -0.59 0.81 0 0" /> 

59 0.81 -0.81 0.59 0 0" /> 

31 0.95 -0.95 0.31 0 0" /> 

00 1.00 - 1.00 0.00 0 0 " /> 

31 0.95 0.95 0.31 0 0" /> 

59 0.81 0.81 0.59 0 0" /> 

81 0.59 0.59 0.81 0 0" /> 

95 0.31 0.31 0.95 0 0" /> 

00 0.00 0.00 1.00 0 0 " /> 


〈TextBlock Text="0%" Canvas. Left="-115" Canvas .Top="-6" /> 
〈TextBlock Text="20%" Canvas. Left="-104" Canvas .Top="-65" /> 
〈TextBlock Text="40%" Canvas. Left="-42" Canvas .Top="-105" /> 
〈TextBlock Text="60%" Canvas. Left="25" Canvas .Top="-105" /> 
〈TextBlock Text="80%" Canvas. Left="82" Canvas .Top="-65" /> 
〈TextBlock Text="100%" Canvas. Left="100" Canvas .Top="-6" /> 

<!-- Arrow to point to percentage --> 

〈Polygon Poi nts="5 55-5 -75 0" 

Stroke="Black" 

Fill="Red"> 

〈 Polygon•RenderTransform> 

<RotateTransform 

Angl e="{Binding El ementName=ProgressBarIndi cator, 

Path=Width}" /> 

</Polygon.RenderTransform> 

</Polygon> 

</Canvas> 

</Border> 

</Gri d> 

</ControlTemplate> 

</Page.Resources 〉 
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<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Grid.RowDefinitions> 

〈RowDefinition Height="Auto" /> 

< RowDefi nit ion Height:'’*” /> 

</Grid.RowDefinitions> 

<ProgressBar Grid. Row="0" 

Tempi ate="{StaticResource progressTempl ate}" 

Margin="48" 

Val ue="{Binding ElementName=sl ider, Path=Value}" /> 

〈Slider Name="sl ider" 

Grid.Row="l" 

Margin="48" 

VerticalAli gnment="Center" /> 

</Grid> 

</Page> 


The bottom of the XAML file instantiates a ProgressBor with this template and binds it to a Slider 
for testing purposes: 



The SpringLoadedSlider and SpeedometerProgressBar are based on XAML files I originally created 
for WPF for an article in the January 2007 issue of MSDN Magazine. Although I needed to alter the 
templates somewhat to account for the differences between WPF and the Windows Runtime, for the 
most part they are quite similar. Although we don’t have complete portability between all XAML- 
based environments, it is certainly the case that work done six years ago can be readily adapted to 
newer platforms. 
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Custom Controls 


When you create a custom control in a Windows Runtime library, you probably want to make that 
control available to a variety of applications and perhaps even market it to other programmers. In this 
case, you should supply a default Style for that control, including a default ControlTemplote. 

A library that contains custom control classes should also contain a file named generic.xaml in a 
folder named Themes. Like the generic.xaml file you’ve already seen, this generic.xaml file has a root 
element of ResourceDictionory and contains a Style definition with a TorgetType indicating the custom 
control name and no dictionary key. This Style should incorporate a default ControlTemplote. 

Visual Studio will generate a skeleton generic.xaml file for you. In the 
Petzold.ProgrammingWindows6.Chapterll library I’ve been using for this chapter, I invoked the Add 
New Item dialog box and selected Templated Control, giving it a name of NewToggle. Visual Studio 
generated a NewToggle.es file with a bunch of using directives and the following class definition: 


namespace Petzold.ProgrammingWindows6.Chapterll 

{ 

public sealed cl ass NewToggle : Control 

{ 

public NewToggleO 

{ 

this.DefaultStyleKey = typeof (NewToggl e) ; 

} 

} 

} 

This is not a partial class definition! There is no corresponding NewToggle.xaml file, and the 
constructor does not contain a call to InitiolizeComponent. The DefaultStyleKey property indicates the 
type to use when searching for implicit styles. 

Visual Studio also generated a Themes folder and a generic.xaml file containing this implicit style: 

<ResourceDictionary 

xml ns="http: //schemas.microsoft.com/winfx/2006/xaml/presentati on" 
xml ns : x="http://schemas.microsoft.com/winfx/2006/xaml" 
xml ns : 1ocal ="using : Petzold.ProgrammingWindows6.Chapterll"> 

<Style TargetType=" local : NewToggle"> 

〈Setter Property="Templ ate"> 

<Setter.Value> 

<ControlTemplate TargetType=" local : NewToggle"> 

<Border 

Background="{TemplateBi nding Background}" 

BorderBrush=" {TempiateBinding Borde 「 Brush}" 

BorderThickness=" {TempiateBinding BorderThickness}"> 

</Border> 

〈 /ControlTempiate> 

</Setter.Value> 

</Setter> 

</Style> 

</ResourceDictionary> 
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If your library has multiple custom controls, this same file will contain default Style definitions for 
all of them. This file has a specific name and location for a reason: It will forever be associated with the 
custom control defined in this library and doesn’t need to be referenced in any other way. 

The NewToggle control is intended to implement toggle button functionality by showing two 
different pieces of content at the same time, one associated with the unchecked state and the other 
with the checked state. Tap one of those pieces of content to change the check state. How the visuals 
change to reflect that change is the responsibility of the template. 

I made NewToggle derive from ContentControl so that it inherits the Content and ContentTemplate 
properties. The class defines two new dependency properties, CheckedContent and IsChecked: 

Project: Petzold.ProgrammingWindows6.Chapterll | File: NewToggle.es 

public class NewToggle : ContentControl 

{ 

public event EventHandler CheckedChanged; 

Button uncheckButton, checkButton; 

static NewToggle() 

{ 

CheckedContentProperty = DependencyProperty .Regi ster("CheckedContent" , 
typeof (object) , 
typeof (NewToggl e), 
new PropertyMetadata(nul1 )); 

IsCheckedProperty = DependencyProperty .Regi ster("IsChecked" , 
typeof (bool) , 
typeof (NewToggl e), 

new PropertyMetadata(fal se , OnCheckedChanged)); 

} 

public NewToggle() 

{ 

this .DefaultStyleKey = typeof (NewToggl e); 

} 

public static DependencyProperty CheckedContentProperty { private set; get; } 

public static DependencyProperty IsCheckedProperty { private set; get; } 

public object CheckedContent 

{ 

set { SetValue(CheckedContentProperty, value); } 
get { return GetValue(CheckedContentProperty); } 

} 

public bool IsChecked 

{ 

set { SetValue(IsCheckedProperty, value); } 
get { return (bool )GetValue(IsCheckedProperty); } 

} 

protected override void OnApplyTemplateC) 
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if (uncheckButton != null) 

uncheckButton.Click -= OnButtonClick; 

if (checkButton != null) 

checkButton.Click -= OnButtonClick; 

uncheckButton = GetTemplateChi1d(" UncheckButton") as Button ; 
checkButton = GetTemplateChi1d ("CheckButton") as Button ; 

if (uncheckButton != null) 

uncheckButton.Click += OnButtonClick; 

if (checkButton != null) 

checkButton.Click += OnButtonClick; 

base.OnApplyTemplateC); 

} 

void OnButtonCli ck(object sender, RoutedEventArgs args) 

{ 

this .IsChecked = sender == checkButton; 

} 

static void OnCheckedChangedCDependencyObject obj, 

DependencyPropertyChangedEventArgs args) 

{ 

(obj as NewToggle) .OnCheckedChanged(EventArgs.Empty); 

} 

protected virtual void OnCheckedChanged(EventArgs args) 

{ 

VisualStateManager. GoToStateCthi s , 

this .IsChecked ? "Checked" : "Unchecked" , 
true) ; 

if (CheckedChanged != null) 

CheckedChanged(thi s , args); 

} 

} 


The OnApplyTemplote override assumes that the template has two Button controls with the names 
"UncheckButton" and "CheckButton.” If so, these are saved as fields and Click handlers are attached. If 
one of these buttons is then clicked, the IsChecked property is changed, the CheckedChanged event is 
fired, and the static VisualStoteManoger.GoToStote is called with states of "Checked" or "Unchecked." 

The template in generic.xaml contains the two buttons with these names as well as Storyboard 
objects defined for the two states: 


Project: Petzold.ProgrammingWindowsll.Chapterll | File: generic.xaml (excerpt) 

<Style TargetType=" local : NewToggle% 

〈Setter Property=" BorderBrush" Val ue="{StaticResource ApplicationForegroundThemeBrush}" /> 
〈Setter Property="BorderThi ckness" Value="l" /> 

<Setter Prope rty="Templ ate"> 

<Setter.Value> 

<ControlTempi ate TargetType=" local : NewToggle"> 
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<Border Background="{TemplateBi nding Background}" 

BorderBrush=" {TempiateBinding BorderBrush}" 

BorderThi ckness="{TemplateBinding BorderThickness}"> 


<VisualStateManager.VisualStateGroups> 

<VisualStateGroup x: Name="CheckStates"> 

<VisualState x: Name="Unchecked" /> 

<VisualState x:Name="Checked"> 

<Storyboard> 

<Obj ectAni mati onllsi ngKeyFrames 

Storyboard .TargetName="UncheckButton" 
Storyboard.TargetPrope rty=" BorderThickness"> 
<DiscreteObjectKeyFrame KeyTime="0" 

Value= M 0" /> 

</Obj ectAni mati onllsi ngKeyFrames> 

<Obj ectAni mati onllsi ngKeyFrames 

Storyboard .TargetName="CheckButton" 
Storyboard.TargetPrope rty=" BorderThickness"> 
<DiscreteObjectKeyFrame KeyTime="0" 

Value="8" /> 

</Obj ectAni mati onllsi ngKeyFrames> 

</Storyboard> 

</VisualState> 

</VisualStateGroup> 

</VisualStateManager.Visual StateGroups> 


<local : UniformGrid Rows="l"> 

〈Button Name="UncheckButton" 

Content="{TemplateBinding Content}" 

ContentTempl ate="{TemplateBinding ContentTemplate} 
FontSi ze="{TemplateBinding FontSi ze}" 
BorderBrush="Red" 

BorderThi ckness="8" 

HorizontalAli gnment="Stretch" /> 

〈Button Name="CheckButton" 

Content="{TemplateBinding CheckedContent}" 
ContentTempl ate="{TemplateBinding ContentTemplate} 
FontSi ze="{TemplateBinding FontSi ze}" 
BorderBrush="Green" 

BorderThi ckness="0" 

HorizontalAli gnment="Stretch" /> 

</local : UniformGrid> 

</Border> 

</ControlTemplate> 

</Setter.Value> 

</Setter> 

〈 /Style 〉 


Keep in mind that in more extensive templates, the two buttons can themselves be templated. 
Here they contain template bindings to the Content and CheckedContent properties and share the 
same ContentTemplate of the control. The item that's checked is highlighted with a thick border, red 
for the left button and green for the right button. 


CHAPTER 11 The Three Templates 


533 


This NewToggle control is demonstrated by the NewToggleDemo project: 


Project: NewToggleDemo I File: MainPage.xaml (excerpt) 

<Page … > 

<Page.Resources 〉 

<Style TargetType="chll: NewToggle"> 

〈Setter Property="Hori zontalA1ignment" Val ue="Center" /> 
〈Setter Property="Verti calA1ignment" Val ue="Center" /> 
</Style> 

</Page.Resources 〉 


<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Grid.ColumnDefinitions> 

<ColumnDefinition Width="*" /> 

<ColumnDefinition Width="*" /> 

</Grid.ColumnDefiniti ons> 


<chll:NewToggle Content="Don 't do it!" 

CheckedContent="Let 's go for it!" 

Grid.Col umn="0" 

FontSize="24" /> 

<chll:NewToggle Grid.Col umn="l"> 

<chll:NewToggle.Content> 

clmage Sou rce="Images/MunchSc ream.jpg" /> 
</chll:NewToggle.Content> 

<chll:NewToggle.CheckedContent> 

<Image Source="Images/Botti cel 1iVenus.jpg" /> 
</chll:NewToggle.CheckedContent> 

</chll:NewToggle> 

</Gri d> 

</Page> 


The first NewToggle has content that consists of two text strings. It’s in an unchecked state. The 
second NewToggle uses two famous images for the two states and is currently checked: 



534 PART Elementals 






In Chapter 13, "Touch, Etc.,’’ I have another example of a custom control called XYSlider. 


If you're using a custom control in a single application, you can define the control right in the 
application project, and the default template can indeed go in a XAML file that contributes to a 
partial class definition for the control. 


Templates and Item Containers 

Templating an ItemsControl derivative such as List Box is very similar to templating any other type 
of control except that the template contains an element named ItemsPresenter. This is basically a 
placeholder that represents the list of items. It requires no template bindings. As you can see by 
looking at the default template for List Box, the bulk of the template is a ScrollViewer. You can replace 
ScrollViewer in a List Box if you find that you can code something better or more appropriate for your 
application. 

As you tap or click an item in a List Box, or as you use the keyboard arrow keys to navigate through 
the list, the selected item is highlighted. Where does that highlight come from? Who is responsible? 

The class actually performing the highlighting belongs to a category of ContentControl derivatives 
I haven’t discussed yet These are controls that derive from Selectorltem: 

Object 

DependencyObject 

UlElement 

FrameworkElement 

Control 

ContentControl 

Selectorltem (non-instantiable) 

ComboBoxItem 

FlipViewItem 

GridViewItem 

ListBoxItem 

ListViewItem 

These five classes map to the five instantiable classes that derive from Selector, as shown earlier in this 
chapter, and they are used to host the individual items in those items controls. ItemsControl has no 
class for its items because the items can’t be selected. 

You haven’t seen these classes yet because normally you don’t instantiate them on your own. 
Instead, the Selector control itself is responsible for generating the items. Because these classes derive 
from ContentControl they have their own default templates (defined in generic.xaml), and these 
templates involve a Con ten t Presen ter. 

Suppose you want to provide a different type of selection highlighting. How is this done? How do 
you apply a style to a ListBoxItem class that you don't even see? 
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ItemsControl defines an ItemContoinerStyle property that you can set to a Style object. When 
working with a List Box, for example, you would provide a Style with a TargetType of ListBoxItem. That 
Style can include a setting for the Template property. 

If you look at the default ListBoxItem style in generic.xaml, you’ll see a visual state group named 
SelectionStotes that has six mutually exclusive states: Unselected, Selected, Selectedilnfocused, 
SelectedDisoblecJ, SelectedPointerOver, and SelectedPressed. 

If you’d like all the selected states to be the same, you can define the template to reflect a selected 
state, and then you can define a Storyboard for the Unselected state. This is the approach I took in the 
CustomListBoxItemStyle project. This is similar to the ListBoxWithltemTemplate project except that it 
also includes a Style set to the ItemContoinerStyle property. 

Project: CustomListBoxItemStyle | File: MainPage.xaml (excerpt) 

<Page … > 

<Page.Resources 〉 

<chll:NamedColor x : Key="namedColor" /> 

</Page.Resources 〉 


<Gri d> 

<ListBox Name="l stbox" 


ItemsSource="{Bi nding Source={Stati cResource namedColor} , 

Path=All}" 


Width="380"> 


<ListBox.ItemTempl ate> 
<DataTemplate> 


</DataTemplate> 

</ListBox.ItemTemplate> 


<ListBox.ItemContainerStyle> 

<Style TargetType="Li stBoxItem"> 

〈Setter Property=" Background" Val ue="T ransparent" /> 

〈Setter Property="TabNavi gation" Val ue="Local " /> 

〈Setter Property="Paddi ng" Value="8,10" /> 

〈Setter Property="Hori zontalContentAlignment" Val ue="Left" /> 

〈Setter Prope rty="Templ ate"> 

<Setter.Value> 

<ControlTempi ate TargetType="Li stBoxItem"> 

〈Border Background="{TemplateBi nding Background}" 

BorderBrush="{TemplateBi nding Borde 「 Brush}" 

BorderThi ckness="{TemplateBinding BorderThickness}"> 


<VisualStateManager.VisualStateGroups> 

<VisualStateGroup x:Name="Sel ectionStates"> 

<VisualState x:Name="Unsel ected"> 

<Storyboard> 

<ObjectAnimationUsingKeyFrames 

Storyboard.Ta rgetName="Con tentPresenter" 
Storyboard.TargetProperty=" FontSty1e"> 
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<DiscreteObjectKeyFrame KeyTime="0" 

Val ue="Normal " /> 
</ObjectAnimationUsingKeyFrames> 


<ObjectAnimationUsingKeyFrames 

Storyboard.TargetName=" ContentPresenter" 
Storyboard.TargetPrope rty="FontWei ght"> 
<DiscreteObjectKeyFrame KeyTime="0" 

Val ue="Normal " /> 
</ObjectAnimationUsingKeyFrames> 
</Storyboard> 

</VisualState> 


<VisualState x : Name="Sel ected" /> 

<VisualState x: Name="SelectedUnfocused" /> 
<VisualState x : Name="Sel ectedDisabled" /> 

<VisualState x : Name="Sel ectedPointerOver" /> 
<VisualState x: Name=" SelectedPressed" /> 

</VisualStateGroup> 

</VisualStateManager.VisualStateGroups> 


<Grid Background="Transparent"> 

〈ContentPresenter x:Name="Con tentPresenter" 


FontStyl e="Ital ic" 

FontWei ght="Bold" 

Content=" {TempiateBinding Content}" 
ContentTransitions= 


</Gri d> 
</Border> 


"{TempiateBindi ng ContentT ransitions}" 
ContentTemplate= 

"{TempiateBi ndi ng ContentTempl ate}" 

HorizontalA1ignment= 

"{TempiateBinding HorizontalContentAlignment} 
VerticalAlignment= 


"{TempiateBinding VerticalContentAlignment}" 
Margi n="{TemplateBinding Padding}" /> 


〈 /ControlTemplate 〉 
</Setter.Value> 


</Setter> 


</Style> 

</ListBox.ItemContai nerStyl e> 
</ListBox> 


<Grid.Background 〉 

<SolidColorBrush Color="{Bi nding ElementName=l stbox, 

Path=Sel ectedltem.Color}" /> 

</Grid.Background 〉 

</Gri d> 

</Page> 
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The Style set to the ItemContoinerStyle of the ListBox can be defined as a resource of course. I 
decided that I wanted a selected item to have text in bold italic, and that’s how the Font Style and 
FontWeight properties of the ContentPresenter are defined. When the item is unselected (which is 
actually the normal case), the Font Style and FontWeight are animated to normal. Here’s how it looks: 



Comsilk 


Crimson 


Cyan 


DarkBlue 


DarkCyan 


DarkGoldenrod 


That’s a rather odd way to highlight an item, but for some applications an unusual highlighting 
might be exactly what is desired. 


The real purpose of templates is not to make controls more unusual (although that is certainly fun) 
but to make them more usable — to adapt the visuals of the control to its functionality. 

In the next chapter I’ll continue the discussion of items controls with the ListViewBose derivatives 
(ListView and GridView) and explore the use of these controls with view models. 
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CHAPTER 12 


Pages and Navigation 


M ost Windows 8 applications are built around instances of the Page class. This is certainly not a 
requirement, but it offers some conveniences such as the easy integration of application bars. 
Up until this chapter, I’ve been focusing on programs that have only one instance of a Page deriva¬ 
tive called Main Page, but now is the time to explore programs that allow Web-like navigation among 
multiple Page derivatives. 

Visual Studio has two project templates for applications with multiple pages called Grid App and 
Split App. These templates are built around the powerful ListView and Grid View controls and use 
these controls with view models. These templates are also layout-aware, meaning that they respond 
to changes in screen orientation and snap modes, so an exploration into window resizing issues offers 
a convenient place to begin this chapter. 

Responding to window size changes is not new to Windows programmers. Most traditional 
Windows desktop programs have a sizing border that allows the user a great deal of control over 
the size and aspect ratio of the application’s window. Windows programmers have been taught for 
25 years to try to write their programs to adapt to whatever size the user selects. Of course, this is 
not always feasible: What’s a spreadsheet program to do if the user shrinks the window down so far 
that no cells are visible? Some programs — for example, the Windows Calculator — simply set a fixed 
window size adequate to display all the program’s content. For traditional desktop applications, this is 
suitable only when the window is guaranteed to be smaller than the screen. 

Windows 8 applications mostly run in full screen mode and actually have a greater assurance of 
getting a minimum screen size. However, Windows 8 applications are also susceptible to changes in 
orientation and snap modes, and many applications should be aware of these changes. 


Screen Resolution Issues 


A computer screen has a particular horizontal and vertical size in pixels and also a physical size that 
is usually specified as a diagonal measurement in inches. Using the Pythagorean Theorem, you can 
combine these sizes and calculate a resolution in pixels per inch, also known as dots per inch (DPI). 

For example, a 1024 x 768 pixel screen has a diagonal of 1280 pixels. If the screen measures 12 
inches diagonally, that’s a resolution of 106 DPI. A 23-inch desktop monitor with a standard high- 
definition size of 1920 x 1080 pixels has about 2203 pixels on the diagonal for a resolution of 96 DPI. 
A 27-inch monitor with 2560 x 1440 pixels has a resolution of about 109 DPI. 
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Early on in this book, I said that it’s proper to assume that the screen has a resolution of 96 pixels 
per inch. As you can see, this is a good assumption for these three example monitors, although you 
might encounter monitors where this rule is stretched somewhat: For much of this book I’ve been 
using a Samsung tablet that has a pixel size of 1366 x 768, with a 11.6-inch diagonal of about 1567 
pixels, for a resolution of 135 DPI. When I draw a 96-pixel square on this screen, I want it to be a 
square inch, it’s closer to 7/10 th inch square. 

The 96 DPI assumption most commonly breaks down for small screens with lots of pixels. For 
example, consider a 10.6-inch screen that crams in 1920 x 1080 pixels. Such a screen has a resolution 
of 208 DPI, so what the programmer thinks is an inch actually shows up as less than half an inch. Text 
gets tinier and although it might still be readable because of the high pixel density, it probably offers 
an insufficiently large touch target. 

For this reason, Windows 8 attempts to compensate for high-resolution screens in a manner that 
is fairly transparent to applications: If a screen has a pixel size of 2560 x 1440 or above and a physical 
size — for example, 12 inches — that results in a resolution of 240 DPI or greater, Windows adjusts all 
pixel coordinates and dimensions used or encountered by the application by 180 percent. The 2560 x 
1440 screen appears to the application to have a size of 1422 x 800 pixels. 

If a screen doesn’t have quite that high a pixel density but it does have a pixel size of 1920 x 1080 
or greater and a physical size small enough to result in a resolution of 174 DPI or greater, Windows 8 
adjusts all pixel dimensions by 140 percent, so a 1920 x 1080 display seems to have a size of 1371 x 
771 pixels. 

Keep in mind that these automatic adjustments occur only for physically small screens with many 
pixels. A physically large screen that has an actual resolution of under 174 DPI will not be adjusted, 
and hence the application will see the full size. 

The Windows Runtime refers to the assumed resolution of the video display as a logical DPI. 
Normally, the logical DPI is 96, but for displays of high pixel density, logical DPI can be either 134.4 
(that is, 96 DPI scaled by 140 percent) or 172.8 (96 DPI scaled by 180 percent). 

Let’s see how this works. The WhatRes program is similar to the WhatSize program first introduced 
in Chapter 3, "Basic Event Handling,” but in addition to displaying the size of the window (which is 
also the size of the page), it obtains information about the resolution of the screen. 

The XAML file in WhatRes simply instantiates a TextBlock.. 


Project: WhatRes I File: MainPage.xaml (excerpt) 

<Crid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

〈TextBlock Name="textBl ock" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Center" 

FontSize="24" /> 

</Grid> 

The code-behind file sets handlers for the SizeChonged event of the page and also the static 
LogicalDpiChanged event from the DisplayProperties class defined in the Windows.Graphics.Display 
namespace. 
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Project: WhatRes I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 


public MainPage() 

{ 

this .InitializeComponent(); 

this .SizeChanged += OnMainPageSizeChanged; 

DisplayProperties .Logical Dpi Changed += OnLogical Dpi Changed; 

Loaded += (sender, args)=> 

{ 

UpdateDisplay(); 

}； 

} 


void OnMai nPageSi zeChanged(object sender, SizeChangedEventArgs args) 

{ 

UpdateDisplay(); 

} 

void OnLogical Dpi Changed(object sender) 

{ 

UpdateDisplay(); 

} 


void UpdateDisplay() 

{ 

double logical Dpi = DisplayProperties. Logical Dpi; 

int pi xelWidth = (i nt)Math .Round(logical Dpi * this .ActualWidth / 96); 

int pixel Height = (i nt) Math .Round(1ogical Dpi * thi s. ActualHeight / 96); 

textBlock.Text = 

String. Format ("Window size = {0} x {l}\r\n" + 

"ResolutionScale = {2}\r\n" + 

"Logical DPI = {3}\r\n M + 

"Pixel size = {4} x {5}", 

this .ActualWidth, this .ActualHeight, 

DisplayProperties .Resoluti onScale, 

DisplayProperties .Logical Dpi, 
pixelWidth, pixelHeight); 



In real life, the DisplayProperties.LogicalDpiChonged event will not be fired very often because 
video displays don’t change pixel size or physical size while a program is running. However, the event 
could be fired if a second monitor is attached to a Windows 8 computer, the two monitors have 
different logical DPI settings, and the program is moved from one display to another. 

The WhatRes program obtains the window size by using the ActuolWidth and ActualHeight 
properties of the page, but then it calculates an actual pixel size based on the DisplayProperties 
.LogicalDpi setting. 
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Here’s how the program looks on the 1366 x 768 tablet I’ve been using for most of this book: 


Window size = 1366 x 768 
ResolutionScale = Scale"! OOPercent 
Logical DPI = 96 
Pixel size = 1366x768 


Like most of the other screen shots in this book, this screen shot has been scaled to 35 percent of its 
pixel size for reproduction on this book page. 

For writing this book, I’ve also been using a 1920 x 1080 monitor with a 21.5-inch diagonal and an 
actual resolution of 102 DPI. Here’s how this program looks on that screen: 


Window size = 1920 x 1080 
ResolutionScale = Scalel OOPercent 
Logical DPI = 96 
Pixel size = 1920x1080 
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This screen shot has a greater pixel dimension than the previous screen shot, so I had to size it to 25 
percent to occupy the same area on this page of the book. In real life, the text is about the same size 
whether the program is running on the tablet or the big screen, but the text is smaller relative to the 
big screen, indicating the application has a bigger area in which to play. 

WhatRes is a good program to run on the Windows 8 simulator that you can select from the 
standard toolbar in Visual Studio. The simulator allows you to run the application in some common 
display sizes. For example, here’s WhatRes running on a simulated 1920 x 1080 display with a 10.6- 
inch diagonal: 


Window size = 1371.42858886719 x 771.428588867188 
ResolutionScale = Scale140Percent 
Logical DPI = 134.4 
Pixel size = 1920 x 1080 


Like the previous screen shot, this screen shot has been scaled to 25 percent to fit on this page. To the 
Windows 8 application, the window appears to have a dimension of 1371 x 771, and all the text and 
graphics it displays will be based on that size. The calculated pixel size matches the pixel dimensions 
of the display. As you can see, the 18-point text appears to occupy about the same relative area of the 
screen as the 1366 x 768 display. 
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Here’s the same program running on a simulated 2560 x 1440 pixel 10.6-inch screen: 


Window size = 1422.22229003906 x 800 
ResolutionScale = Scale"! 80Pe「cent 
Logical DPI = 172.8 
Pixel size = 2560 x 1440 


This screen shot has been scaled to 19 percent for reproduction on this book page, but notice again 
that the application perceives a screen size that is quite close to 1366 x 768 and the text occupies the 
same relative area of the screen. 

Now let’s use the simulator to run on a monitor with a large physical size. The pixel dimension here 
is also 2560 x 1440, but the simulated screen size is 27 inches, so no adjustment is made: 



ResolutionScale = ScalelOOPercent 

Logical DPI = 96 

Pixel size = 2560x 1440 
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Like the previous screen shot, I had to reduce the size to 19 percent, which makes the text appear 
very tiny. However, this text has quite a reasonable size on a 27-inch monitor, and what the tiny text 
here really indicates is how the application has a much roomier playground in which to stretch out. 


Scaling Issues 


As a Windows programmer, you're accustomed to dealing with coordinates and sizes in units of pixels. 
As you’ve seen, when your program runs on a physically small screen with a high pixel density, Win¬ 
dows scales these coordinates and sizes by 140 percent or 180 percent, depending on the display size 
and resolution. 

So, instead of saying that we draw or size controls in pixels, we might more correctly say that 
we deal in device-independent units (DIUs), or simply units. Some people refer to these units as 
device-independent pixels, but that seems like too much of an oxymoron to my ears. 

In the following table, the first column shows the units you use in a program for drawing and 
sizing, and the other columns show how these translate to the actual pixels of the video display: 



Resolution Scale 

DIUs 

100% 

140% 

180% 

5 

5 

7 

9 

10 

10 

14 

18 

15 

15 

21 

27 

20 

20 

28 

36 


You can continue the chart yourself. 

What this chart shows is that if you stick with sizes and coordinates that are multiples of five units, 
these units convert to an integral number of pixels. This integral conversion can sometimes help in 
preserving the fidelity of the graphics. 

When Windows makes these adjustments, it scales text and vector graphics without loss of 
resolution. For example, if you specify a Fontsize of 20 and your program runs on a display with 180 
percent resolution scale, you don’t get a 20-pixel-tall font scaled up by 180 percent with resultant 
jaggies or blurring. You get a smooth authentic 36-pixel Fonts ize font. 

But bitmaps are different. Bitmaps have particular pixel sizes, and if you display a 200-pixel-square 
bitmap at its actual pixel size, there is no choice for Windows except to scale this image by 140 per¬ 
cent or 180 percent to make it larger and hence fuzzier. 

To avoid this problem, you can create bitmaps in three different sizes (for example, 200-pixel- 
square, 280-pixel-square, and 360-pixel-square) for use by your application. It’s even possible to store 
these images as program assets and have Windows automatically select the correct one! 
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The AutolmageSelection project demonstrates how this is done. I started with a rather high- 
resolution bitmap and cropped it to 2304 pixels square size. Working from that, 丨 then resized the 
image three times: to 640 pixels square, to 896 pixels square, and to 1152 pixels square. These cor¬ 
respond to the three resolution scales: 896 pixels is 140 percent of 640, and 1152 pixels is 180 percent 
of 640. I also used Windows Paint to embed some text in each image indicating the actual pixel size. I 
had to use three different text sizes to make the text approximately the same size in all three images. 

I then added these three images to the AutolmageSelection project twice in two different folders 
with two different naming conventions, as shown here in the Visual Studio Solution Explorer: 



In the Imagesl folder, the three bitmaps have been given different names. Notice that periods 
separate the 〃 scale-100 〃，〃 scale-140〃，and 〃 scale-180 〃 parts of the name from the "PetzoldTablet" 
name and the "jpg" extension. 

In the Images2 directory, the three bitmaps have identical names, but they reside in three different 
subfolders indicating the scaling. 


In both cases, the scale-100 bitmap is 640 pixels square, the scale-140 bitmap is 896 pixels square, 
and the scale-180 bitmap is 1152 pixels square. 

The MainPage.xaml file contains two Image elements that reference a bitmap in the Imagesl and 
Images2 directories. In both cases, the part of the filename or file path indicating the scaling is absent 
from these paths: 

Project: AutolmageSelection I File: MainPage.xaml (excerpt) 

<Grid Background:” {StaticResource ApplicationPageBackgroundThemeBrush}"> 

<Grid.ColumnDefinitions> 

<ColumnDefinition Width="*" /> 

<ColumnDefinition Width="*" /> 

</Grid.ColumnDefiniti ons> 
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clmage Source="Imagesl/Petzol dTablet.jpg" 
Grid.Column="0" 

Width="640" 

Height="640" 

HorizontalA1i gnment="Center" 

VerticalA1i gnment="Center" /> 

clmage Sou rce="Images2/Petzol dTablet.jpg" 
Grid.Column="l" 

Width="640" 

Height="640" 

HorizontalA1i gnment="Center" 

VerticalA1i gnment="Center" /> 

</Grid> 


Notice that the two Image elements are given explicit Width and Height settings corresponding 
to the pixel size of the 100 percent bitmap. This is crucial! Don’t count on a Stretch mode of None to 
force the Image element to perform the scaling correctly. 

Let’s run this program on three different 10.6-inch diagonal (simulated) monitors. (When you’re 
doing this with the Windows 8 simulator, don’t switch resolutions while the program is running. 
Instead, terminate the program, switch resolutions, and then run the program again.) Here’s the 
1366 x 768 display: 



As usual, this 1366 x 768 screen shot is scaled to 35 percent for the page. 
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Here’s the program running on a 1920 x 1080 monitor with a 10.6-inch diagonal: 



This screen shot is sized to 25 percent to fit on the page. Even though a Windows 8 program per¬ 
ceives this display to have a 1371 x 771 pixel size, the 896-pixel-square bitmap has been chosen and 
effectively displayed in its native size: Each pixel of the bitmap corresponds to a pixel of the display. 

And here’s the program running on a 2560 x 1440 monitor with a 10.6-inch diagonal: 



The screen shot has been sized to 19 percent, but on a real display there will be a one-to-one 
correspondence between the bitmap pixels and the screen pixels. 
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When run on screens of the same physical size, the bitmaps should also have the same physical 
size, as shown in these examples, but the rendition of the bitmap should be better for screens of 
higher density, as is also the case. On displays of a larger physical size, the images will be much 
smaller relative to the size of the screen but roughly the same physical size. 


Snap Views 


A Windows 8 machine requires a display of at least 1024 x 768 pixels to run Windows Store 
applications. This display size has an aspect ratio of 4:3, consistent with movies before the advent of 
widescreen in the early 1950s and consistent with classical television and computer displays prior to 
widescreen. 

On a tablet the screen can switch between landscape and portrait modes, so a display size of 
768 x 1024 will also be encountered by applications running on this machine. But on a display of this 
size, these are the only two dimensions that a Windows Store application needs to handle. 

The next step up is a display of 1366 x 768, which has an aspect ratio of approximately 16:9, 
consistent with high-definition television. Such a display has a portrait mode of 768 x 1366. 

In addition, 1366 x 768 is the smallest display size that supports snap modes. Snap modes allow 
two programs to share the screen, but they are available only in the landscape orientation. 


The Windows.Ul.ViewManogement namespace contains an ApplicationView class with a static 
property named Value that is of type ApplicationViewStote, an enumeration that indicates the current 
snap mode of an application. There is no event corresponding with this information. If your program 
needs to be notified when the view changes, check the value during a SizeChanged handler. 

The WhatSnap program is similar to WhatRes except that it includes a display of the 
ApplicotionView.Value property: 


Project: WhatSnap I File: MainPage.xaml.es (excerpt) 

void UpdateDisplayO 

{ 

double logical Dpi = DisplayProperties .Logical Dpi; 

int pixel Width = (i nt) Math. Round(logical Dpi * this .ActualWidth / 96); 

int pixel Height = (i nt)Math .Round(logicalDpi * this. ActualHeight / 96); 

textBlock.Text = 

String .Format ("ApplicationViewState = {0}\r\n" + 

"Window size = {1} x {2}\r\n" + 

"ResolutionScale = {3}\r\n" + 

"Logical DPI = {4}\r\n" + 

"Pixel size = {5} x {6}", 

ApplicationView. Value, 

this. ActualWidth, this. ActualHeight, 

DisplayProperties .ResolutionScal e, 

DisplayProperties. Logical Dpi , 
pixelWidth, pixelHeight); 
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In addition, the Text Block is in a Viewbox so that it can still be viewed if the screen gets too narrow: 


Project: WhatSnap | File: MainPage.xaml (excerpt) 

<Grid Background=" {StaticResource ApplicationPageBackgroundThemeBrush}"> 
<Viewbox HorizontalAli gnment="Center" 

VerticalAli gnment="Center" 

StretchDirecti on="DownOnl y" 

Margin="24"> 


<TextBlock Name="textBl ock" 


</Viewbox> 
</Crid> 


FontSize="24" /> 


The ApplicotionViewStote enumeration has four members. In portrait mode, the only applicable 
member is FullScreenPortroit: 


ApplicationViewState = FullScreenPortrait 
Window size = 768 x 1366 
ResolutionScale = ScalelOOPercent 
Logical DPI = 96 
Pixel size = 768 x 1366 
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Snap modes play a role in landscape only. If the application occupies the full screen, the 
ApplicotionViewStote has a value of FullScreenLondscope: 


ApplicationViewState = FullScreenLandscape 
Window size = 1366 x 768 
ResolutionScale = ScalelOOPercent 
Logical DPI = 96 
Pixel size = 1366x768 


If you sweep your finger on the left edge of the screen just a bit and then go back, you can get a 
columnar display of other applications. If you drag your finger farther, you can bring another program 
into a partial view. At this point, the ApplicotionViewStote becomes Filled: 



BING WEATHER 


63 


Cloudy 



68753 。 

Partly Cloudy 


60751 。 


ApplicationViewState = Filled 
Window size = 1024 x 768 
ResolutionScale = ScalelOOPercent 
Logical DPI = 96 
Pixel size = 1024x768 


59751 。 


54747° 

Light Showers 
60 % 4 

53745° 

Light Showers 


Notice that for a minimum size screen that supports snap modes — 1366 x 768 — the Filled size is 
1024 x 768, which is the minimum size screen that runs Windows Store applications. 
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Drag that bar farther to the right, and ApplicotionViewStote becomes Snapped: 



ApplicationViewState = Snapped 
Window size = 320 x 768 
ResolutionScale = ScalelOOPercent 
Logical DPI = 96 
Pixel size = 320x768 


Those are the only four possibilities. You get the same Snapped value if your application is on the 
left rather than the right: 


ApplicationViewState = Snapped 
Window size = 320 x 768 
ResolutionScale = ScalelOOPercent 
Logical DPI = 96 
Pixel size = 320 x 768 
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Continue dragging that bar to the right, and your program goes into the Filled mode again: 



BING WEATHER 


ApplicationViewState = Filled 
Window size = 1024 x 768 
ResolutionScale = ScalelOOPercent 
Logical DPI = 96 
Pixel size = 1024x768 


63。 


Cloudy 

Feels Like 63° 


68753° 


6075 T 

Light Showers 


59751° 


54747° 

Light Showers 



The Snapped view is always 320 units wide. The Filled view is always the total screen width minus 
320 units for the other application minus 22 units for the drag bar. 


For example, if you run this program on a 2560 x 1440 pixel 10.6-inch diagonal display, the screen 
has a total width of 1422 units, which separates into 1080 units for the Filled mode, 320 units for the 
Snapped mode, and 22 units for the divider. 


If you run the program on a 2560 x 1440 pixel 27-inch diagonal display, device-independent units 
are the same as pixels. The screen has a total width of 2560 units, which separates into 2218 units for 
the Filled mode, 320 units for the Snapped mode, and 22 units for the divider. 


In the Filled mode, a program can determine the full size of the screen in device-independent units 
by adding 320 and 22 to the width. By further incorporating the LogicalDpi setting, the program can 
determine the full size of the screen in pixels. 

Because there are a very limited number of display modes — and particularly because the Snapped 
mode always has a width of 320 units — it is expected that applications will be tailored to do some¬ 
thing intelligent for each mode. As you can see, the Bing Weather application reorients its display 
of daily weather forecasts for the Snapped mode. However, it’s unlikely you’ll need to do something 
different for the Filled mode. 


Changing the orientation of a StackPonel is one simple way to deal with the Snapped mode. 
Juggling rows and columns of a Grid is another, as I demonstrated in the OrientableColorScroll 
program in Chapter 5, "Control Interaction.” Later in this chapter, you’ll see that it’s possible to switch 
between a Grid View and a ListView for displaying collections of items. 

But obviously there is no solution that will be adequate for every application. This is really an issue 
that needs to be addressed individually. 
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The ApplicationView class has a static Tryilnsnap method that attempts to unsnap a foreground 
application, but using this method is discouraged and it’s hard to think of a reason to do so. 

Orientation Changes 

At the same time that youYe adapting your application to Filled and Snapped modes, you can also 
adapt your application to landscape and portrait modes. Even if you believe that your application 
will run only on a desktop and never a tablet, you should be aware that some desktop monitors are 
capable of flipping into portrait mode and these monitors are much appreciated by people who tend 
to do a lot of writing. 

You’ve seen earlier in this chapter that the ApplicationView.Value property indicates portrait mode 
with the ApplicotionViewStote.FullScreenPortrait enumeration member, but if you need more informa¬ 
tion — and if you’d prefer an event that tells you when orientation changes — then you’ll want to use 
the DisplayProperties class in the Windows.Graphics.Display namespace. This is the same class that 
provides the logical DPI scaling information. 

The Windows.Grophics.Display namespace defines a DisplayOrientotions enumeration with five 
members, shown here with their values in parentheses: 


■ None (0) Used only for DisployProperties.AutoRototionPreferences 

■ Landscape (1) 90 degrees clockwise rotation from PortraitFlipped 

■ Portrait (2) 90 degrees clockwise rotation from Landscape 

■ LondscapeFlipped (4) 90 degrees clockwise rotation from Portrait 

■ PortraitFlipped (8) 90 degrees clockwise rotation from LondscapeFlipped 

The "90 degrees clockwise rotation" mentioned here refers to the user turning the tablet (or 
computer screen) 90 degrees clockwise. As you’ve seen, Windows 8 automatically responds by 
rotating the contents of the screen in the opposite direction so that it maintains the same orientation. 

The static DisplayProperties.NativeOrientation property indicates the orientation of the screen 
that is "native" or "most natural.’’ This can be either Landscape or Portrait, generally governed on the 
location of buttons or logos on the device. The static DisployProperties.CurrentOrientotion can be any 
of the non-zero values. 

The DisplayProperties. Orientation Changed event is fired when CurrentOrientation changes (as 
a result of the user turning the screen) or NotiveOrientotion changes, which happens more rarely 
when an application is moved to another monitor. This OrientationChongecJ event is not fired 
when an application starts up regardless of the initial orientation, so it’s a good idea to duplicate 
OrientotionChanged event handling during program initialization. 
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The XAML file in the NativeUp program displays an arrow pointing up: 


Project: NativeUp I File: MainPage.xaml (excerpt) 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<StackPanel HorizontalAli gnment="Center" 

VerticalAli gnment="Center" 

RenderTransformOrigin="0. 5 0.5"> 

〈Path Data="M 100 0 L 200 100, 150 100, 150 500, 50 500, 50 100, 0 100 Z" 
Stroke="Yel low" 

StrokeThi ckness="12" 

Fill="Red n 

RenderTransformOrigin="0. 5 0.5" 

HorizontalAli gnment="Center" /> 

<TextBlock Text="Nati ve Up" 

FontSize= n 96 M /> 


<StackPanel.RenderTransform> 

<RotateTransform x: Name=" rotate" /> 
</StackPanel.RenderTransform> 
</StackPanel> 

</Grid> 


Normally, if you run such a program on a tablet and turn it around in your hands, Windows 8 
would change the orientation of the display so that the arrow always points up, or nearly up given the 
90 degree increments of rotation. 

However, the code-behind file in this particular program uses the Orientation Changed event to 
counteract that rotation. The result is that the arrow always points toward the top of the computer as 
if the program were not subject to orientation changes: 


Project: NativeUp I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

public MainPage() 

{ 

this. Ini tializeComponent(); 


SetRotationC); 

DisplayProperties .OrientationChanged += OnOrientationChanged; 

} 

void OnOrientati onChanged(object sender) 

{ 

SetRotationC )； 

} 

void SetRotation() 

{ 

rotate.Angle 

} 

i nt Log2 (Di splayOrientations orientation) 



Log2 (Di splayProperties .NativeOrientation)); 
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int value = (int)orientation; 
int log = 0; 


while (value > 0 && (value & 1) == 0) 


value >>= 1; 
log += 1; 


return log; 


For example, suppose you start the program in its native orientation. The arrow points up. Then 
you turn the tablet 90 degrees clockwise. Windows reorients the program 90 degrees counterclock¬ 
wise, but the Orientation Changed handler turns the text and arrow 90 degrees clockwise. You can still 
see that there’s an orientation change occurring because the screen contracts slightly, but the arrow’s 
orientation relative to the screen doesn’t change. 

The program relies on the values of the DisployOrientotions enumeration members being 1, 2, 4, 
and 8 in order of clockwise rotation. The base-2 logarithms of these values are 0, 1, 2, and 3, so each 
increase by 1 is equivalent to a 90 degree clockwise change. 

It is possible for an application to request a particular desired orientation. There are two ways to 
do this. You can open the Package.appmanifest file in Visual Studio, select the Application Ul tab, and 
check one or more of the four orientations: 



□ □ n 


□ 



I I Landscape-flipped □ Portrait-flipped 


Whatever you select becomes the initial value of the static DisplayProperties 
.AutoRo tot ion Preferen ces property, but during program initialization you can set that property to one 
or more DisployOrientotions enumeration members combined with the C# bitwise OR operator (|). 

The key word here is preferences. Windows 8 is free to ignore what you request. For example, if 
you request that your application run only in portrait mode but the program happens to be running 
on a desktop computer with a landscape screen, the program will run in landscape mode. Even if the 
application is running on a tablet but the tablet is in a docking station in landscape mode, it’s only 
going to run in landscape. 

In other words, Windows 8 overrides the program’s preferences if the preferences don’t make 
sense in the current environment. This is reasonable: Regardless of what the program wants, the user 
shouldn’t be required to look at the screen sideways. 

I recommend that you avoid specifying orientation preferences and instead code your program 
to accommodate all orientations. The only possible exceptions to this rule involve games that rely 
upon bitmap graphics that must be oriented in a particular way, or programs that make use of the 
orientation sensors such as those in Chapter 18, "Sensors and GPS.” 
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But keep in mind that restricting your program to a particular orientation might cause user 
confusion. For example, suppose you request that your program run only in landscape mode but 
it’s running on a tablet that the user is holding in portrait mode. Normally, the user swipes a finger 
on the left or right of the screen to invoke the application switcher or charms bar. If the program is 
running in landscape mode, but the tablet is held in portrait mode, the user must swipe the top or 
bottom of the screen to invoke the application switcher or charms bar, and these two features will be 
displayed sideways because they have the same orientation as the current application. 

Simple Page Navigation 

Until this point, virtually all the applications in this book have been built around a single instance of 
a class called Main Page that derives from Page. As a result, it hasn’t even been noticeable that this 
instance of Main Page is set to the Content property of an object of type Frame, and this Frame object 
is set to the Content property of an instance of the Window class. 


You can see this hierarchy come together in the OnLaunched method in the standard App class. 
The actual code (which you’ll see later in this chapter) checks for errors and ensures that initialization 
occurs only once, but basically it does this in the simple case: 

Frame rootFrame = new Frame (); 

Window. Current.Content = rootFrame; 

rootFrame.Navi gate(typeof (MainPage) , args.Arguments); 

Window. Current.Activate(); 

Frame derives from ContentControl, but the Content property isn’t set directly. Instead, the 
Navigate method accepts a Type argument that references a Page derivative. The Navigate method 
instantiates this type (in this case Mo in Page) and this instance becomes the Content property of the 
Frame object and the main focus of user interaction. 

Within your programs, you’ll use this same Navigate method to move from one page to another. 
Navigate comes in two versions: The version in the OnLaunched method passes some data to the 
Page object, but the other version does not. (You’ll see how this works later in this chapter.) 

Very conveniently, the Page class defines a Frame property, so within a Page derivative you can call 
Navigate like so: 


this. Frame.Navigate(pageType); 

Within a multipage application, Navigate is often called numerous times with various Page type 
arguments. Internally, the Frame class maintains a stack of visited pages. The Frame class also defines 
GoBack and Go Forward methods, as well as CanGoBack and CanGoForward properties of type bool. 

The SimplePageNavigation project contains two classes that derive from Page rather than just 
one. I’ve continued to use the Blank App template for this project, so the MainPage class is created 
by Visual Studio as usual. To add another Page derivative to a project, I selected Add New Item from 
the Project menu and then Blank Page (not Basic Page) from the Add New Item dialog. I gave my new 
page class a name of SecondPoge. 


CHAPTER 12 Pages and Navigation 


557 



The SimplePageNavigation project demonstrates how pages can navigate to each other in a 
variety of ways. MainPage.xaml instantiates a TextBlock to identify the page, a TextBox to enter some 
text, and three buttons with the text "Go to Second Page," "Go Forward," and "Go Back ”： 

Project: SimplePageNavigation I File: MainPage.xaml (excerpt) 

<Page … > 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

<StackPanel> 

<TextBlock Text="Mai n Page" 

FontSize="48" 

HorizontalAli gnment="Center" 

Margin="48" /> 

<TextBox Name="txtbox" 

Width="320" 

HorizontalAli gnment="Center" 

Margin="48" /> 

〈Button Content="Go to Second Page" 

HorizontalAli gnment="Center" 

Margin="48" 

Cli ck="OnGotoButtonCl ick" /> 

〈Button Name="forwardButton" 

Content="Go Forward" 

HorizontalAli gnment="Center" 

Margin="48" 

Cli ck="OnForwardButtonCl ick" /> 

〈Button Name="backButton" 

Content="Go Back" 

HorizontalAli gnment="Center" 

Margin="48" 

Cli ck="OnBackButtonCl i ck" /> 

</StackPanel> 

</Gri d> 

</Page> 


The code-behind file uses the OnNavigatedTo override to enable the forward and back buttons 
depending on the CanGoForward and ConGoBock properties defined by Frame. The three Click 
handlers call Navigate (referencing the SecondPoge object), GoForworcJ, and GoBack: 

Project: SimplePageNavigation | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

public MainPage() 

{ 

this .InitializeComponent(); 

} 
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protected override void OnNavigatedTo(Navi gationEventArgs args) 

{ 

forwardButton.IsEnabled = this .Frame.CanGoForward; 
backButton.IsEnabled = this. Frame.CanGoBack; 

} 

void OnGotoButtonCli ck(object sender, RoutedEventArgs args) 

{ 

this .Frame.Navi gate(typeof (SecondPage)) ; 

} 

void OnForwardButtonCli ck(object sender, RoutedEventArgs args) 

{ 

thi s . Frame .GoForwardO ; 

} 

void OnBackButtonCli ck(object sender, RoutedEventArgs args) 

{ 

this .Frame.GoBack(); 

} 

} 

The SecondPage class is exactly the same except that it uses the OnGotoButtonClick method to 
navigate to MainPage: 

Project: SimplePageNavigation | File: SecondPage.xaml.es (excerpt) 

void OnGotoButtonCli ck(object sender, RoutedEventArgs args) 

{ 

this .Frame.Navi gate (typeof (MainPage)) ; 


Here’s how the program appears when you first run it: 



CHAPTER 12 Pages and Navigation 


559 




Neither the forward nor the back button is enabled. When you click the "Go to Second Page” 
button, the program navigates to that page: 



Now the "Go Back” button is enabled, and it will take you back to Main Page. The "Go to Second 
Page" will do that as well, but with a difference: When you press "Go Back” to go back to Mo in Page, 
the "Go Forward" button will be enabled but "Go Back” will not be. When you press "Go to Second 
Page," "Go Back" will be enabled but "Go Forward” won’t be. 

Before we begin exploring this in detail, I want to show you another way to enable the "Go 
Forward" and "Go Back” buttons. The CanGoBack and ConGoForward properties of Frame can be 
Binding sources, like so: 

<Page … Name="page"> 

〈Button Name="fo rwardButton" 

IsEnabl ed="{Binding El ementName=page , Path=Frame .CanGoForward}" 

... /> 

〈Button Name="backButton" 

IsEnabl ed="{Binding El ementName=page , Path=Frame .CanGoBack}" 

... /> 

</Page> 

That would eliminate the need for the OnNavigatedTo method in this program, but any program that 
implements page navigation will probably make other uses of that method as well as its companion, 
On Navigated From. 

You’ll discover an important characteristic of navigation if you experiment with 
SimplePageNavigation by pressing the various buttons to navigate, go forward, and go back, all the 
while typing a few characters into each TextBox that you encounter along the way. You will discover 
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that whenever you move from one page to another — whether by means of calls to the Navigate, 
GoForword, or Go Bock methods — the Text Box is initially blank. What this means is that a new instance 
of Mo in Page or Second Page is being created on each Button click. Whatever you’ve typed into that 
TextBox has been lost because the Page instance containing that TextBox has been abandoned. 


This is likely surprising. You probably expect a new instance to be created when you press the 
"Go to Main Page” or "Go to Second Page” button, but you probably also expect that pressing "Go 
Forward” or "Go Back” navigates to a previous instance of the page. But this is not the case. New 
instances are created regardless. 

The Page class defines three virtual methods that assist the page in handling navigation. These 
are named OnNavigatingFrom, On Na viga ted From — notice the tense difference in those two 
method names! — and OnNovigatedTo. If you were to log calls to those three methods, as well as the 
constructor of these Page classes and firings of the Loaded and Unloaded events, you would discover 
the following sequence during the transition from one page to another: 


From Page 

To Page 

OnNavigatingFrom 



Constructor 

OnNavigatedFrom 



OnNavigatedTo 


Loaded 

Unloaded 



This sequence occurs regardless of whether the transition is a result of Navigate, Go Forward, or 
GoBack. 

Up until this chapter, we've been treating Main Page as if it lasts for the duration of the application, 
as it does if it's the only Page derivative around. However, once you begin dealing with multipage 
applications, you need to think about Page derivatives being created and discarded. It’s a good 
idea to architect your Page derivatives so that they attach event handlers and obtain resources 
during OnNovigatedTo or Loaded and detach those handlers and release those resources during 
OnNavigatedFrom or Unloaded. 

If you want a new instance of your Page derivatives created whenever that page is navigated to, 
you're obviously in good shape because this is what happens by default. If you prefer something a 
little different, there are two alternatives, one of which is very easy and the other not quite so easy. 


The easy alternative is setting the NavigationCacheMode property of the Page to something other 
than the default Disabled enumeration member. For example: 

public MainPage() 

{ 

this. InitializeComponentO; 

this .NavigationCacheMode = NavigationCacheMode ■Enabled; 

} 
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The other option is Required, but for this program Enabled and Required both work the same. 

When you set Enabled or Required on a Page object, only one instance of each Page derivative is 
created and cached, and that instance is reused every time the page is visited, regardless of whether 
that occurs with Navigate, Go Forward, or Go Back. The sequence of method calls and events that occur 
is the same as the table shown earlier the first time a particular page type is navigated to; subse¬ 
quently, it’s the same sequence but without the constructor. You can set the NovigationCocheMode 
property differently for different Page classes. 

This option might be ideal for a "hub" architecture where one Main Page can navigate to several 
different secondary pages that can then go back to MainPage. The difference between Enabled and 
Required is that Enabled might cause instantiated pages to be discarded if the number of cached 
pages exceeds the Cache Size property of Frame, which is 10 by default but can be changed. 


In the general case, however, you probably want a new instance to be created for a Navigate call 
but existing instances to be used for Go Forward and GoBack. This option is not provided with a simple 
property setting, but I’ll show you how to do it shortly. 


The Back Stack 


Back in the dark ages, Web browsers had Back buttons but not Forward buttons. The browser 
implemented the Back button in a very simple manner by storing visited pages in a familiar data 
structure known as the stack. In the context of the browser, this was called the back stock: Whenever 
the browser navigated to a new page, it pushed the previous page on the stack. Whenever the user 
pressed the Back button, the browser popped a page off the stack and navigated to that. When the 
stack became empty, the Back button was disabled. 

Implementing a Forward button complicates this process somewhat. Rather than a stack to store 
visited pages, the browser requires an ordered list. (This list is still often referred to as the back stack, 
however.) This list includes the current page. Whenever the browser navigates to a new page, it adds 
that new page to the end of the list. However, when the user presses the Back button, the page being 
navigated from is not removed from the list. That page must remain in the list because the user might 
then press the Forward button. 

For example, perhaps the user begins at a page that 111 call Page Zero and from there navigates 
to Page One, then to Page Two, Page Three, Page Four, and Page Five. The back stack looks like this, 
with the most recent new page at the top and the arrow pointing to the current page: 

Page Five <- 
Page Four 
Page Three 
Page Two 
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Page One 
Page Zero 

Now suppose the user presses the Back button four times. The current page is now Page One: 

Page Five 
Page Four 
Page Three 
Page Two 
Page One <- 
Page Zero 

Then the user presses the Forward button, and the current page is now Page Two: 

Page Five 
Page Four 
Page Three 
Page Two <- 

Page One 
Page Zero 

Obviously, using the Back and Forward buttons, the user can navigate anywhere among these six 
pages. When the current page reaches the bottom, the Back button is disabled. When the current 
page reaches the top, the Forward button is disabled. 

But now suppose that from Page Two the user instead navigates to Page Six. An entire section of 
the list must be discarded. This discarded part of the list has previously been saved for presses of the 
Forward button but those pages are no longer navigable following navigation to a new page: 

Page Six <- 

Page Two 
Page One 
Page Zero 

The Forward button is now disabled. The Forward button will be re-enabled only when the user 
presses the Back button. 

The Frame class internally maintains this back stack of visited pages. However, the back stack is not 
accessible by an application. You can’t even obtain the size of the back stack. 

But you can obtain the position of the current page within the back stack from the get-only 
BackStackDepth property. When an application begins running and navigates to the initial page, 
BackStackDepth reports a value of zero. In the four examples shown earlier, BackStackDepth equals 5, 
1, 2, and 3, respectively. 

This BackStackDepth is important information, for it allows a particular page class to uniquely 
identify a particular instance of itself. Let's see how. 
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Navigation Events and Page Restoration 


In the normal case, when a program calls GoBock or Go Forward to return to a particular page, you 
want the user to see the same content on the previously visited page. You’ve already seen that you 
can't get this automatically: When NavigationCacheMode is set to its default value of Disabled, the 
GoBock and Go Forward calls always result in a new instance of the particular Page class to be created. 
When set to Enabled or Required, existing instances of the Page class are re-used but they’re re-used 
for Navigate as well. 

As I mentioned earlier, the Page class defines three virtual methods that involve navigation. The 
OnNavigatingFrom call kicks off a navigation sequence. This method is not often used. The event 
arguments are of type NovigotingConcelEventArgs that allows the navigation to be cancelled. 


During navigation from one page to another — whether a result of a call to Navigate, GoBack, or 
Go For ward — the OnNavigatedFrom in the first page is followed shortly by a call to OnNovigotedTo in 
the second page. These two methods both have event arguments of type Navigation EventArgs. These 
event arguments are used in other contexts (such as the WebView class), so some of the properties are 
irrelevant when used with these two overrides. Here are the important ones for the navigation events: 

■ The Parameter property of type object. This is set from the optional second argument of the 
Navigate method, and it is used to pass data from one page to another. I’ll have more to say 
about this process shortly. 

■ The Content and SourcePageType properties always refer to the page being navigated to. The 
Content object is the actual instance of the Page derivative, and SourcePageType is the type of 
that instance — in other words, the first argument to the Navigate call used to create that page. 
This information is only of real value in an OnNavigatedFrom override. In an OnNavigatedTo 
override, the Content property is equal to this and SourcePageType is equal to a call to 
GetType. 

■ The NavigationMode property is a member of the NavigationMode enumeration, with 
members New, Refresh, Back, and Forward. The value is New or Refresh for a navigation initiat¬ 
ed by the Navigate method. The value is Refresh if the page is navigating to itself. The value is 
Back or Forward for a navigation initiated by the GoBock or GoForward methods, respectively. 

The NavigationMode property is the key to implementing an architecture where new page content 
is created for Navigate calls (that is, when NavigationMode is New) but not when the page has been 
previously visited and navigation occurs though Back or Forward. 

The first step is for the Page derivative to define a field that allows it to save and restore its state: 

Dicti onary<stri ng , object> pageState; 

You use this dictionary in much the same way you use ApplicationData.LocalSettings dictionary that 
I first demonstrated in connection with the PrimitivePad program in Chapter 7, "Asynchronicity." 
However, instead, of saving application settings during the Application.Suspending event and 
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restoring them when the application runs again, you save page state into the dictionary during the 
On Na viga ted From override and restore it in OnNavigatedTo. 


What is page state? It’s generally input by the user and anything that results from that input: the 
state of check boxes, radio buttons, sliders, and particularly text input. In the sample application 
I’ve been using, the only really important page state is the content of the Text Box. You can save that 
during OnNavigatedFrom with a made-up key name like so: 

pageState. Add("TextBoxText" , txtbox.Text); 

You restore it during OnNavigatedTo.. 

txtbox.Text = pageState ["TextBoxText"] as string; 

There are conceivably other properties of the Text Box you might want to save and restore — for 
example, SelectionStart and SelectionLength — but let's keep it simple for now. 

This process of saving and restoring page state in this dictionary is totally useless if the Page class 
is being instantiated for every navigation event because a new instance of pageState is created as 
part of the new page! What you need in addition is to save instances of this dictionary in another 
dictionary that’s defined as static so that it’s shared among all the instances of that page: 

static Dictionary<int, Dicti onary<stri ng , object» pages; 

The values in this dictionary are the instances of the Dictionary I’ve called pageState. The keys to 
this dictionary are values of BockStockDepth, thus allowing different pageState dictionaries to be 
associated with fixed locations of the page instance within the back stack. 

If you have multiple page derivatives using this same technique, you’ll want to define both 
dictionaries in a Page derivative that you’ll use as a base class for other pages. The static pages 
dictionary can then be shared by all the pages in the application. 

Let’s see how this works in the context of a simple application. The VisitedPageSave program 
defines a class named SoveStotePoge. I used the simple Class template to create this class; there is 
no XAML file associated with it. The class derives from Page, and the two dictionaries are defined as 
protected so that they can be accessed from derived classes: 


Project: VisitedPageSave I File: SaveStatePage.es (excerpt) 

public cl ass SaveStatePage : Page 
{ 

protected Dicti onary<stri ng , object> pageState; 

static protected Dictionary<int, Di cti onary<stri ng , object» pages = 

new Dictionary<int, Di cti onary<stri ng , object»() ; 


} 

The static dictionary is instantiated in its definition (or it could be instantiated in the stat¬ 
ic constructor), and the instance dictionary is not. As you’ll see, it will be instantiated in the 
OnNavigatedTo override when the Na viga tionMode is New. 
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I created a SecondPoge class just as in SimplePageNavigation, but in both the XAML files and code- 
behind files for MoinPoge and SecondPoge I changed the base class from Page to SoveStotePoge. 
Otherwise, the MainPage.xaml and SecondPage.xaml files are the same as in SimplePageNavigation. 
The two code-behind files are basically identical to each other. Here’s MainPage.xaml.es showing the 
same implementations of the button Click handlers you’ve seen before: 


Project: VisitedPageSave I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : SaveStatePage 

{ 

public MainPage() 

{ 

this. InitializeComponent(); 

} 


void OnGotoButtonCli ck(object sender, RoutedEventArgs args) 

{ 

this .Frame.Navi gate(typeof (SecondPage)) ; 

} 

void OnForwardButtonCli ck(object sender, RoutedEventArgs args) 

{ 

this .Frame.GoForwardC); 

} 

void OnBackButtonClick (object sender, RoutedEventArgs args) 

{ 

this .Frame.GoBack(); 

} 

} 


The NavigationCacheMode is left at its default setting of Disabled so that a new page object is 
instantiated during all navigation events. 

In the OnNovigatedTo override, the integer key for the static dictionary is the BackStackDepth 
property. If the NavigationMode is not New, the method simply uses that key to obtain the pogestate 
dictionary corresponding to this location in the back stack, and then it uses that dictionary to initialize 
the page, in this example the Text Box: 


Project: VisitedPageSave | File: MainPage.xaml.es (excerpt) 

protected override void OnNavigatedTo(Navi gationEventArgs args) 

{ 

// Enable buttons 

forwardButton.IsEnabled = this. Frame.CanGoForward; 
backButton.IsEnabled = this .Frame.CanGoBack; 

// Construct a dictionary key 

int pageKey = this .Frame.BackStackDepth; 

if (args.NavigationMode != NavigationMode .New) 
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// Get the page state dictionary for this page 
pageState = pages[pageKey]; 

// Get the page state from the dictionary 
txtbox.Text = pageState[ "TextBoxText"] as string; 


base .OnNavigatedTo(args); 

} 


If the Navigation Mode _\s New, however, we know that this page was reached with a call to 
Navigate and should be regarded as a fresh uninitialized page. This additional logic occurs in the 
implementation of OnNavigatedTo in SoveStatePoge, which you’ll note is called at the end of the 
OnNavigatedTo overrides in MoinPoge and SecondPoge. This code creates a new pageState dictionary 
and adds that to the static pages dictionary: 


Project: VisitedPageSave | File: SaveStatePage.es (excerpt) 

public cl ass SaveStatePage : Page 

{ 

protected override void OnNavigatedTo(Navi gationEventArgs args) 

{ 

i f (args.NavigationMode == NavigationMode .New) 

{ 

// Construct a dictionary key 

int pageKey = this. Frame.BackStackDepth; 

// Remove page key and higher page keys 

for (int key = pageKey; pages.Remove(key); key++); 

// Create a new page state dictionary and save it 
pageState = new Dicti onary<stri ng , object>() ; 
pages.Add(pageKey, pageState); 

} 

base.OnNavigatedTo(args); 

} 

} 

However, the static pages dictionary must also be cleared of any possible entries with equal or 
higher BackStackDepth keys. These entries result from Go Back calls not balanced by Go For word calls. 
The for statement that removes these entries is more comprehensible when you realize that the 
Remove method of Dictionary returns false if the key does not exist: 

for (int key = pageKey; pages.Remove(key); key++); 
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In both Main Page and SecondPage, the On Na viga ted From override is much simpler and just saves 
the page state in the existing page State dictionary: 


Project: VisitedPageSave | File: MainPage.xaml.es (excerpt) 

protected override void OnNavigatedFrom(Navi gationEventArgs args) 
{ 

pageState.Clear(); 

// Save the page state in the dictionary 
pageState. Add("TextBoxText" , txtbox.Text); 


base .OnNavigatedFrom(args); 


Also keep in mind that the pageState dictionary can store many more items — as many as you need 
to re-create the state of the entire page. 

Perhaps the easiest way to check whether this program is working correctly is to simply type 1, 2, 

3, and so forth into the Text Box in consecutive pages. You’ll see those restored entries when you press 
the "Go Forward" and "Go Back” buttons. 

If you suspend and then resume the application from Visual Studio, you’ll see that everything is 
restored correctly. However, the application is not saving anything when it’s suspended, so if the ap¬ 
plication is terminated following suspension, the next time it is launched it will appear in a new and 
pristine state. This is probably not what you desire, but it’s not hard to fix. 

Saving and Restoring Application State 


If an application such as VisitedPageSave is terminated and then relaunched, you probably want the 
program to appear as if it had never been terminated. You probably want all the previously created 
pages to be restored with their previous content, plus you want the application displaying the same 
page that the user last visited. 

In other words, not only do you need to save (and later restore) the state of each page, but you 
need to save (and later restore) the state of the back stack. Restoring the state of each page is actually 
useless without restoring the back stack because without that back stack there’s no record of what 
pages must be restored! 

I mentioned earlier that the back stack is entirely internal to the Frame object. Fortunately, Frame 
provides two methods that let you save and restore the back stack state without knowing its internal 
structure: The GetNavigationState returns a string that you can save in application settings; the next 
time your program runs you can retrieve that string and pass it as an argument to SetNovigationState. 

What is this string? Well, you can look at it if you want. You’ll find that it contains the class 
names of the pages in the back stack with some numbers. What these numbers are is undocu¬ 
mented and might change in the future, so you should really only use this string for passing from 
GetNavigationState to SetNavigationStote. 


568 PART Elementals 



GetNovigotionStote actually does a little more than just return a string that encodes the state of 
the back stack. Calling this method causes the current page to get an On Na viga ted From call with a 
Navigation Mode of Forward. This allows the current page to save its page state, but it also means that 
you just can’t call GetNavigationState any time you want. It should be called only when the applica¬ 
tion is being suspended. An excellent place to do this is in the OnSuspending event handler in App 
•xaml.cs. 

Here’s what I’ve done in a program called ApplicationStateSave: 

Project: ApplicationStateSave | File: App.xaml.es (excerpt) 

private void OnSuspendi ng(object sender, SuspendingEventArgs e) 

{ 

var deferral = e.SuspendingOperation.GetDeferral(); 

//TODO: Save application state and stop any background activity 

// Code added for ApplicationStateSave project 

ApplicationDataContainer appData = ApplicationData. Current.LocalSettings; 

appData.Values ["NavigationState"] = (Wi ndow. Current.Content as Frame) .GetNavigationStateO; 

// End of code added for ApplicationStateSave project 


deferral.CompleteC); 

} 

IVe left the version of OnSuspending that Visual Studio generated intact and merely added two lines 
of code surrounded by comments. This code obtains the GetNavigationState string from the Frame 
and saves it in application settings with a name of "NavigationState." 

Some earlier programs in this book save application settings from MainPage. Why not do the same 
thing here? Recall that Page derivatives in a multipage environment should attach any event handlers 
they need during OnNovigotedTo or Loaded and detach them during OnNovigatedFrom or Unloaded, 
which means that every Page derivative in your application would need to set a Suspending handler to 
perform this job. But this is not really a job for the Page derivative. This job involves saving a naviga¬ 
tion state that defines the navigational relationship among multiple pages, so it should really be the 
responsibility of the application itself. 

That’s one reason why the code goes in the App class. The other reason is that restoring the 
navigation state also needs to go in the App class as well, and actually in a particular place in the App 
class because it’s effectively overriding default logic encoded there. 

To restore the back stack, you call SetNovigotionStote with the saved string originally obtained 
from GetNovigotionStote. Calling SetNavigationState causes navigation to the previously current page. 
The OnNovigotedTo method of that page is called with a NovigationMode of Back, allowing the page 
to reload its own page settings without believing that it’s a new page. 
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It is essential that SetNavigationStote be called at a particular place in the OnLounched method 
in App.xaml.es. Here it is in the ApplicationStateSave project. I’ve left all the generated code and 
comments in OnLaunched intact: 

Project: ApplicationStateSave | File: App.xaml.es (excerpt) 

protected override void OnLaunched (LaunchActivatedEventArgs args) 

{ 

Frame rootFrame = Window. Current.Content as Frame; 

// Do not repeat app initialization when the Window already has content, 

// just ensure that the window is active 
if (rootFrame == null) 

{ 

// Create a Frame to act as the navigation context and navi gate to the first page 
rootFrame = new Frame (); 

if (args.PreviousExecutionState == Appli cationExecutionState.Termi nated) 

{ 

//TODO : Load state from previously suspended application 
// Code added for ApplicationStateSave project 

ApplicationDataContainer appData = ApplicationData .Current.LocalSettings; 

if (appData.Values.ContainsKey ("NavigationState")) 

rootFrame.SetNavigationState(appData.Values ["Navigati onState"] as string) ; 

// End of code added for ApplicationStateSave project 

} 

// PI ace the frame in the current Window 
Window. Current.Content = rootFrame; 

} 

if (rootFrame.Content == null) 

{ 

// When the navigation stack isn't restored navi gate to the first page, 

// configuring the new page by passing required information as a navigation 
// parameter 

if (!rootFrame.Navi gate(typeof (Mai nPage) , args.Arguments)) 

{ 

throw new Excepti on("Fai1ed to create initial page") ; 

} 

} 

// Ensure the current window is active 
Window. Current.ActivateC); 


Again, I’ve used comments to identify the code I’ve added for this project. (Notice the ellipsis 
down at the bottom. I’ll discuss the additional code I’ve added to App.xaml.es in the next section.) 

Toward the bottom of the OnLaunched method is a call to the Navigate method with the 
Main Page class. You do not want this call to occur if you are restoring the back state because this 
Navigate call will navigate away from the previously current page and possibly cause part of the back 
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stack to be removed in the OnNavigatedTo method of Main Page. For this reason, the back stack must 
be restored prior to this call, which ensures that the Content property of the Frame object is set to the 
previously current page and the navigation to Main Page is skipped. 


The code you’ve seen so far saves and restores the back stack. The second part of this job in¬ 
volves saving and restoring all the page states. In the previous project, I defined a class named 
SaveStotePage that maintained two dictionaries — one instance and one static — for saving page state. 
Both Main Page and SecondPoge derived from this class. 

I’ve retained that architecture for this program. Indeed, Main Page and SecondPoge are identical to 
the classes in the previous project. But SaveStotePage has been enhanced to save all the settings for 
all the pages in application local storage, and to retrieve them. 

If a particular back stack references four instances of Main Page and three instances of SecondPoge, 
there is a total of seven settings with the key name "TextBoxText.” These must all be distinguished 
from each other. Fortunately, the ApplicotionDotoContoiner used for storing application settings has a 
"container" feature, somewhat similar to folders or subdirectories. This feature seems ideal for isolat¬ 
ing the settings for each page. The container is identified by a name, and the name I chose for each 
Page instance indicates the location of that instance within the back stack, which is the same as the 
integer key of the pages dictionary converted to a string. 

Here’s both the static constructor and the Suspending handler in this enhanced version of 
SaveStotePage. The handler for the Suspending event is attached by the static constructor so that it’s 
only executed once to save the settings for all the pages, of course without knowing anything about 
those settings: 

Project: ApplicationStateSave | File: SaveStatePage.es (excerpt) 

public class SaveStatePage : Page 
{ 

protected Dicti onary<stri ng , object> pageState; 

static protected Di cti onary<i nt , Di cti onary<stri ng , object» pages = 

new Dictionary<int, Di cti onary<stri ng , object»() ; 


static SaveStatePageO 
{ 

// Set handler for Suspending event 

Application .Current.Suspending += OnApplicationSuspending; 

ApplicationDataContainer appData = ApplicationData. Current.LocalSettings; 

// Loop through containers, one for each page in the back stack 
foreach (Appl icationDataContainer container in appData.Containers.Values) 

{ 

// Create a page state dictionary for that page 

Di cti onary<stri ng , object> pageState = new Dicti onary<st ring , object>() ; 

// Fill it up with saved values 

foreach (string key in container.Values.Keys) 

{ 

pageState.Add(key ， container.Values[key]); 
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// Save in static dictionary 

int pageKey = Int32 .Parse(container.Name); 

pages[pageKey] = pageState; 



static void OnApplicationSuspendi ng(object sender, SuspendingEventArgs args) 

{ 

ApplicationDataContainer appData = ApplicationData. Current.LocalSettings; 

foreach (int pageKey in pages.Keys) 

{ 

// Create container based on location within back state 
string containerName = pageKey.ToString(); 

// Get container with that name and clear it 
ApplicationDataContainer container = 

appData.CreateContainer(containerName, 

ApplicationDataCreateDisposition .Always); 

container.Values.Clear(); 

// Save settings for each page in that container 
foreach (string key in pages[pageKey].Keys) 

container.Values.AddCkey, pages[pageKey][key]); 



By the time the static constructor concludes, the pages dictionary contains one entry for each page 
on the back stack. None of these individual pages has yet been instantiated. As each SoveStatePage 
derivative is instantiated, however, it obtains its own pageState dictionary during the OnNavigotedTo 
override, either by retrieving it from the pages dictionary or by creating a new one. 


Navigational Accelerators and Mouse Buttons 


Do you use a mouse that has five buttons rather than the usual three? Neither do I, but some people 
do, and some of those people are accustomed to using the extra two buttons to navigate forward 
and back in Internet Explorer. Other Internet Explorer users have become accustomed to using the 
left and right arrow keys in conjunction with Alt to navigate back and forward. Some keyboards have 
special keys to perform these operations. 

You might want to implement these same shortcuts to allow users to navigate among the pages 
of your application. To do this, you need two events that you haven’t seen yet: PointerPressed and 
AccelerotorKeyActivated. 

The AccelerotorKeyActivated event isn't available in the Page or Frame classes or even the Window 
class that underlies Frame. But it is available from CoreWindow, which is the object that supports input 
events for Window, and you can obtain the CoreWindow object from the current Window object. 
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The handler for Accelerator Key Activated gets first dibs on keystrokes, and if this handler identifies a 
particular key as a command accelerator, it can inhibit further visibility of that key by the application 
by setting the Handled property of the event arguments to true. 

As you'll learn in Chapter 13, "Touch, Etc.," the PointerPressed event is fired for a mouse but¬ 
ton press or a finger or pen touching the screen. This event is defined by UlElement and inherited 
by Frame and Page, but for purposes of getting button clicks for page navigation, you can define a 
handler for this event on the CoreWindow as well. 


Because these keyboard and mouse accelerators function at a higher level than the page, it is 
convenient to put them in the App class. 

Earlier I showed you an OnLaunched method in the App class of the ApplicationStateSave project. 
That method had an ellipsis at the bottom indicating that the method contains a bit more code. Here 
it is: 

Project: ApplicationStateSave | File: App.xaml.es (excerpt) 

protected override void OnLaunched(LaunchActi vatedEventArgs args) 

{ 

// Code added for ApplicationStateSave project 

Window. Current.CoreWindow.Dispatcher.AcceleratorKeyActivated += OnAcceleratorKeyActivated; 
Window. Current.CoreWindow.PointerPressed += OnPointerPressed; 

// End of code added for ApplicationStateSave project 


The PointerPressed event handler is the simpler of the two, so let’s look at that first. The states of 
all five mouse buttons are available from the Properties property of the CurrentPoint property of the 
event arguments. The two extra buttons commonly used for navigation are identified as XButtonl 
and XButton2. We’re only interested in cases where all the regular buttons are unpressed and only 
one of these extra buttons is pressed — that is, their states aren’t equal to each other: 

Project: ApplicationStateSave | File: App.xaml.es (excerpt) 

void OnPointerPressed(CoreWi ndow sender, PointerEventArgs args) 

{ 

PointerPointProperties props = args.CurrentPoint.Properties; 

if (!props.IsLeftButtonPressed && 

!props.IsMiddleButtonPressed && 

!props.IsRightButtonPressed && 

props.IsXButtonlPressed != props.IsXButton2Pressed) 

{ 

if (props.IsXButtonlPressed) 

GoBackO ; 

else 

GoForwardO; 
args.Handled = true; 

} 

} 


void GoBackO 
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Frame frame = Window. Current.Content as Frame ; 

if (frame != null && frame.CanGoBack) 
frame.GoBackC); 

} 

void GoForward() 

{ 

Frame frame = Window. Current.Content as Frame ; 


if (frame != null && frame.CanGoForward) 
frame.GoForwardO ; 


If the event results in a call to the Go Bock or Go Forward method, the event handler sets the Handled 
property of the event arguments to true. 


For the keyboard accelerators, the event handler is able to use members of the VirtuolKey 
enumeration for the Left and Right arrow keys, but VirtuolKey doesn’t have members for the special 
browser keys. In the Win32 API, these are identified as VK_BROWSER_BACK and 
VK_BROWSER_FORWARD and have values of 166 and 167, respectively: 

Project: ApplicationStateSave | File: App.xaml.es (excerpt) 

void OnAcceleratorKeyActivated(CoreDi spatcher sender, AcceleratorKeyEventArgs args) 

{ 

if ((args.EventType == CoreAcceleratorKeyEventType .SystemKeyDown || 
args.EventType == CoreAcceleratorKeyEventType .KeyDown) && 

(args.VirtualKey == VirtualKey .Left || 
args.VirtualKey == VirtualKey. Right || 

(int) args.VirtualKey == 166 || 

(int) args.VirtualKey == 167)) 

{ 

CoreWindow window = Window. Current.CoreWindow; 

CoreVirtualKeyStates down = CoreVirtualKeyStates .Down; 

// Ignore key combinations where Shi ft or Ctrl is down 
if ((window.GetKeyState(Vi rtualKey■ Shi ft) & down) == down || 

(window.GetKeyState(Vi rtualKey .Control) & down) == down) 

{ 

return ; 

} 

// Get alt key state 

bool alt = (window.GetKeyState(Vi rtualKey .Menu) & down) == down; 


// Go back for Alt-Left key or browser left key 
if (args.VirtualKey == VirtualKey .Left && alt || 
(int)args .VirtualKey == 166 && !alt) 

{ 

GoBackC); 

args.Handled = true ; 
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// Go forward for Alt-Right key or browser right key 
if (args.VirtualKey == VirtualKey .Right && alt || 

(int)args .VirtualKey == 167 && !alt) 

{ 

GoForwardC); 

args.Handled = true; 



The Left and Right arrow keys function as accelerators only when the Alt key (also known as the 
Menu key) is down but neither Shift nor Ctrl is down, and the special browser keys are accepted only 
when no modifier key is down. 

The GetKeyState method is a little clumsy to use because it can return one of three members of 
the CoreVirtuolKeyStotes enumeration: None (equal to 0), Down (equal to 1), or Locked (equal to 2). 
Internally, all the keys are treated as toggles, and the enumeration members are flags. A key that is up 
begins with a key state of 0. When the key is pressed, it has a state of 3 ; and when it is released, it has 
a state of 2. Press it down again for a state of 1, and release it to 0 again. 


Passing and Returning Data 

Very often pages need to share data. It’s common for pages to share a view model, for example. 

A good place to maintain data shared among pages is the App class. Don't hesitate about adding 
methods and properties to this class. For example, you can add a public property named ViewModel 
that has a public get accessor but a private set accessor so that the property can be initialized in the 
App constructor. 

On the other hand, under the philosophy that data should be visible only to classes that need to 
know this data, don’t put everything in the App class. There are very structured ways for one page to 
pass data to another page during navigation and for the second page to return data to the first page. 

The Data Passing And Returning project has two simple pages that demonstrate these techniques. 
The first page is called Main Page as usual, and the second page is called DiologPoge because it func¬ 
tions much like a dialog box. Main Page can navigate only to DialogPage, and DiologPoge can only go 
back to Main Page. 

Because the navigation between these two pages is limited, the pages don’t need to save page 
state. To keep the program even simpler, it doesn’t save navigation state or page state during 
suspension and it doesn’t implement keyboard or mouse shortcuts. Despite the simplicity of the 
program, it illustrates basic data-passing techniques. 
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The XAML file for DiologPoge has three RocJioButton controls for Red, Green, and Blue, and a 
regular Button labeled "Finished": 


Project: DataPassingAndReturning I File: DialogPage.xaml (excerpt) 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<StackPanel> 

<TextBlock Text="Color Dialog" 

FontSi ze="48" 

HorizontalAli gnment="Center" 

Margin="48" /> 

<StackPanel Name=" radioStack" 

HorizontalAli gnment="Center" 

Margin="48"> 

<RadioButton Content="Red" Margi n="12"> 

<RadioButton.Tag> 

<Color>Red</Color> 

</RadioButton.Tag> 

</RadioButton> 


<RadioButton Content="Green" Margi n="12"> 
<RadioButton.Tag> 

<Color>Green</Color> 

</RadioButton.Tag> 

</RadioButton> 


<RadioButton Content="Bl ue" Margi n="12"> 
<RadioButton.Tag> 

<Color>Blue</Color> 

</RadioButton.Tag> 

</RadioButton> 

</StackPanel> 


<Button Content="Fi nished" 

HorizontalAli gnment="Center" 
Margi n="48" 

Cli ck="OnReturnButtonClick" /> 
</StackPanel> 

</Crid> 


Notice that each RocJioButton has its Tag property set to a Color value corresponding to that button. 
The code-behind file for DiologPoge is responsible for obtaining the selected Color from these 
buttons and returning that back to Main Page. 

Interestingly, MainPage.xaml is very similar to DialogPage.xaml, except that the Grid has a name, 
the middle RocJioButton is checked, and the Button is labeled "Get Color”: 

Project: DataPassingAndReturning I File: MainPage.xaml (excerpt) 

<Grid Name="contentGri d" 

Background=" {StaticResource ApplicationPageBackgroundThemeBrush}"> 

<StackPanel> 

<TextBlock Text="Mai n Page" 

FontSi ze="48" 
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HorizontalAli gnment="Center" 
Margin="48" /> 


<StackPanel Name=" radioStack" 

HorizontalAli gnment="Center" 
Margin="48"> 

<RadioButton Content="Red" Margi n="12"> 
<RadioButton.Tag> 

<Color>Red</Color> 

</RadioButton.Tag> 

</RadioButton> 


<RadioButton Content="Green" Margi n="12 

IsChecked="True"> 

<RadioButton.Tag> 

<Color>Green</Color> 
</RadioButton.Tag> 

</RadioButton> 


<RadioButton Content="Bl ue" Margi n="12"> 
<RadioButton.Tag> 

<Color>Blue</Color> 

</RadioButton.Tag> 

</RadioButton> 

</StackPanel> 


<Button Content="Get Color" 

HorizontalAli gnment="Center" 
Margi n="48" 

Cli ck="OnGotoButtonClick" /> 
</StackPanel> 

</Grid> 


The idea here is that you use the RadioButton controls in MainPage to select an initial value for the 
RacJioButton controls in DialogPage, which means that Main Page needs to pass data to DialogPage. 

The data that Main Page and DialogPage are passing between each other is only a Color value, 
but for real applications it could be much, much more. Let’s reflect that possibility by defining 
classes specifically for the purpose of passing data between pages. Here’s the class for the data that 
Main Page passes to DialogPage: 

Project: DataPassingAndReturning I File: PassData.es 
using Windows.UI; 

namespace DataPassingAndReturning 

{ 

public cl ass PassData 

{ 

public Col or InitializeColor { set; get ; } 

} 

} 
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For this simple example, the data returned from DiologPoge to MoinPoge is quite similar: 


Project: DataPassingAndReturning I File: ReturnData.es 
using Windows.UI; 

namespace DataPassingAndReturning 

{ 

public cl ass ReturnData 

{ 

public Col or ReturnColor { set ; get; } 

} 

} 

I could have used the same class in this example, of course, but in the general case you’ll be using 
different classes for these two tasks. 

Watch out! rm going to be jumping back and forth between the Main Page and DiologPoge 
code-behind files in accordance with the flow of logic and data. 

The easy transfer of data is from MainPage to DiologPoge. When you click the "Get Color” button 
in MoinPoge, the code-behind file creates an object of type Pass Do to and then scans through the 
collection of RodioButton controls to see which one is checked. That’s the Color value assigned to the 
InitializeColor property of PassData. That Pass Do to object then becomes the second argument to 
Navigate: 

Project: DataPassingAndReturning I File: MainPage.xaml.es (excerpt) 

void OnGotoButtonCli ck(object sender, RoutedEventArgs args) 

{ 

// Create PassData object 
PassData passData = new PassDataO ; 

// Set the InitializeColor property from the RadioButton controls 
foreach (UIE1ement child in radioStack.Children) 
if ((child as RadioButton) .IsChecked.Value) 

passData.InitializeColor = (Color) (child as RadioButton) .Tag; 

// Pass that object to Navi gate 

this. Frame■Navi gate(typeof (DialogPage) ， passData); 

} 

When the OnNovigotedTo override in DiologPoge is called, the Parameter property of the event 
arguments is the object passed as the second argument to Navigate. DiologPoge uses that to initialize 
its own set of RodioButton controls: 

Project: DataPassingAndReturning I File: DialogPage.xaml.es (excerpt) 

protected override void OnNavigatedTo(Navi gationEventArgs args) 

{ 

// Get the object passed as the second argument to Navi gate 
PassData passData = args.Parameter as PassData; 

// Use that to initialize the RadioButton controls 
foreach (UIE1ement child in radioStack.Chi 1dren) 

if ((Color) (chiId as RadioButton) .Tag == passData.InitializeColor) 

(child as RadioButton). IsChecked = true; 
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base .OnNavigatedTo(args); 

} 


Now you can click the three RadioButton controls to select a Color value. When satisfied with the 
selection press the Finished button. The handler simply calls GoBack to return to MoinPage. 

Project: DataPassingAndReturning | File: DialogPage.xaml.es (excerpt) 

void OnReturnButtonCli ck(object sender, RoutedEventArgs args) 

{ 

this .Frame.GoBackO; 

} 


It would be nice if GoBack had an optional parameter that you could set to return data to the 
target page. But it does not. There is no mechanism for doing this, and another technique is required. 

One possibility is this: After DialogPoge calls GoBack, the OnNavigatedFrom override in DialogPage 
is called. The Content property of the event arguments is the instance of MainPage about to be navi¬ 
gated to. This means that MainPage could define a public property or method expressly for obtaining 
information from DialogPage, and DialogPage could set that property or call that method during its 
OnNavigatedFrom override. 

Architecturally, though, it’s a little cheesy because DialogPage must be familiar with the page types 
that are navigating to it. In general, this is not a good solution. 


A much better solution is for DialogPage to define a Completed event with the type of the data it 
needs to return: 


Project: DataPassingAndReturning I File: DialogPage.xaml.es (excerpt) 

public sealed partial class DialogPage : Page 
{ 

public event EventHandler<ReturnData> Completed; 


MainPage needs to set a handler for that event. The only place MoinPage can do this is within 
the OnNavigatedFrom method because the event arguments include a Content property that is the 
instance of DialogPoge that is being navigated to: 


Project: DataPassingAndReturning I File: MainPage.xaml.es (excerpt) 

protected override void OnNavigatedFrom(Navi gationEventArgs args) 

{ 

if (args■SourcePageType.Equals (typeof (Di al ogPage))) 

(args.Content as DialogPage) .Completed += OnDialogPageCompleted; 

base .OnNavigatedFrom(args); 


MainPage knows about DialogPage because it’s navigating to DialogPage. But it could be 
navigating to other pages as well, so it checks the SourcePageType property of the event arguments 
to make sure that it knows what type of page this particular OnNavigatedFrom event indicates. 
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With this scheme, DialogPage doesn’t need to know about Main Page, and that’s how it should be. 
Hiding a consumer of information from the provider of information is one of the primary purposes of 
events within the context of object-oriented programming. 

DialogPage could fire the Completed event in the Click handler for the Button, but I’ve chosen to 
implement that logic in On No vigotedFrom. 


Project: DataPassingAndReturning I File: DialogPage.xaml.es (excerpt) 

protected override void OnNavigatedFrom(Navi gationEventArgs args) 

{ 

if (Completed != null) 

{ 

// Create ReturnData object 

ReturnData returnData = new ReturnDataO ; 

// Set the ReturnColor property from the RadioButton controls 
foreach (UIE1 ement chi 1d in radioStack.Children) 
if ((child as RadioButton) .IsChecked.Value) 

returnData.ReturnColor = (Color) (child as RadioButton) .Tag; 

// Fire the Completed event 
Compl eted(thi s , returnData); 

} 

base .OnNavigatedFrom(args); 

} 

If there is indeed a handler for the Completed event, DialogPage instantiates a ReturnData object and 
then sets the ReturnColor property from the collection of RadioButton controls. 

In the Completed handler, Main Page uses the data from DiologPoge to set the Background 
property of its Grid and check a RadioButton: 

Project: DataPassingAndReturning I File: MainPage.xaml.es (excerpt) 

void OnDialogPageCompleted (object sender, ReturnData args) 

{ 

// Set background from returned color 

contentGrid.Background = new SolidColorBrush (args.ReturnColor); 

// Set RadioButton for returned color 

foreach (UIE1ement child in radioStack.Children) 

if ((Color) (child as RadioButton) .Tag == args.ReturnColor) 

(child as RadioButton) .IsChecked = true; 

(sender as DialogPage) .Completed -= OnDialogPageCompleted; 

} 

The handler concludes by detaching itself from the sender. 

But there’s a flaw in the code as I’ve presented it: By default, the instance of Main Page that sets 
a handler for the Completed event in DialogPage is not the instance of Main Page that DiologPoge 
returns back to! To fix that little problem requires setting NovigotionCocheMode to something other 
than Disabled. 
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Project: DataPassingAndReturning I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 
{ 

public MainPageO 
{ 

this .Ini ti alizeComponent(); 

this .NavigationCacheMode = NavigationCacheMode. Enabled; 



You only need to do this in MoinPoge, and guaranteeing a single instance makes perfect sense for 
a page that is architecturally the hub of the application. The instance of MainPage that invokes 
DialogPage should be the same instance that gets data back from it. 

Visual Studio Standard Templates 

A confession: I’ve been coding page-navigation logic in various Windows environments for several 
years now, and it never occurred to me to implement shortcuts with accelerator keys or mouse 
buttons. The code I showed you earlier is adapted from a class generated by Visual Studio named 
LayoutAwarePage that derives from Page and implements several helpful features. 

LayoutAwarePage and other assorted classes are automatically added to your Visual Studio 
projects when you invoke the Add New Item dialog box and add an item called Basic Page rather than 
Blank Page. These files are also part of the Grid App and Split App templates. The page class created 
by selecting Basic Page derives from Layout AwarePage rather than just Page. Layout AwarePage 
defines virtual methods named Save State and Load State that allow the page instance to save and load 
its state and that do much of the work for you in conjunction with another generated class named 
Suspension Manager. 

Layout AwarePage also works in conjunction with Suspension Manager to save application state 
(including the back stack) when a program is being suspended and reload that state when it’s 
relaunched. 

Layout AwarePage is named as it is because it uses the SizeChonged method to check the 
ApplicotionView.Volue property and call VisuolStoteMonager.GoToStote with strings corresponding to 
the members of the ApplicotionViewStote enumeration: "FullScreenLandscape", "FullScreenPortrait ”， 
"Filled”, and "Snapped". These states allow XAML files to implement view changes themselves through 
Visual State Manager markup. 

It’s up to you whether you want to use these classes or implement these features (or similar 
features) on your own. Whether you use them or not, it doesn’t hurt to study these classes and see 
what you can learn from them. 

When creating new projects in Visual Studio, I’ve been using Blank App, but there are two 
alternatives: Grid App and Split App. These templates make use of LayoutAwarePage and 
SuspensionMonager, as well as a sample view model in the DotoModel folder. These templates 
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demonstrate a recommended approach to laying out data on the screen. Perhaps most important, 
the Grid App and Split App templates demonstrate rudimentary use of the two remaining 
ItemsControl derivatives: Grid View and ListView. 

Both Grid View and ListView derive from ItemsControl by way of Selector and ListViewBase. Neither 
Grid View nor ListView defines any public properties or methods on its own, but they share many 
properties and methods from ListViewBase. Also, if you check generic.xaml, you'll discover that the 
templates for GridView, ListView, GridViewItem, and ListView Item are different. In particular, by default 
Grid View uses a WrapGricJ for displaying its items, and ListView uses a VirtualizingStackPonel. 

Grid View and ListView are also suitable for grouping items. You define how the items are grouped, 
and the appearance of a header that delimits the groups. You’ll see examples of this in the Grid App 
and Split App templates. 

The Windows 8 start screen itself is a GridView or something very similar to a GridView. As you 
probably know, you can swipe items on the start screen to select them. This type of selection is 
supported by ListViewBase (and hence by GridView and ListView), but it is disabled in the Visual 
Studio templates. 

The Windows 8 start screen allows you to move items around. This feature is also supported 
by ListViewBase (but interestingly, not while items are grouped). The Windows 8 start screen also 
supports semantic zoom: If you use your fingers to pinch the start screen, it collapses to give you 
a broader view of the groups, and then you can select whole groups. You can do this in your own 
application by using the SemanticZoom class. 

For now, let’s take a closer look at the Grid App template. (You can study Split App on your own.) 
The project contains three LayoutAworePage derivatives. 

Grid App initializes itself by displaying a GroupedItemsPage. 


GridApp 

Group Title: 1 > 


Group Title: 2 > 



■ 


■ ■ 



In a real application, those gray boxes would probably be pictures or other graphics. 
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The page has a title and a GridView control with horizontal scrolling. The individual items 
are defined by a DataTemplate resource named "Standard250x250ltemTemplate" defined in 
StandardStyles.xaml. The appearance of the headers ("Group Title: 1 >" and so forth) is defined in the 
GroupedItemsPage.xaml file by the HeoderTemplate property of the GroupStyle property of GridView. 

The page has the same appearance in the Filled view, but in the Snapped view it switches to a 
vertically scrollable ListView: 



The ItemTemplate property is now the DataTemplate resource 〃 Standard80ltemTemplate .〃 Notice 
that the page title is also formatted differently. It’s a "SnappedPageHeaderTextStyle" rather than the 
normal "PageHeaderTextStyle,” both defined in StandardStyles.xaml. 


The switch between the GridView and ListView when the program is in a Snapped mode occurs in 
the GroupedltemsPage.xaml file based on the calls to the VisuolStoteMonager in LoyoutAwarePage. 
The GroupedltemsPage.xaml file contains a Visual State Manager section that responds to the 
Snapped state as well as the FullScreenPortrait state. 
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This is a GridView just as in the wider landscape views, but you might notice a little less margin 
around the sides. Defining changes like these in XAML is one of the advantages of using the Visual 
State Manager to signal different views. 

If you click one of the header titles, you’ll navigate to a Group Detail Page.. 
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Notice that the Back button is implemented as a circled arrow in the upper-left corner. The Button 
has its Style set to the "BackButtonStyle" resources defined in StandardStyles.xaml. This is again a 
GridView, except that the header is very large and appears at the left. The individual items are now 
displayed with an ItemTemplate based on the "Standard500xl30ltemTemplate 〃 resources from 
StandardStyles.xaml. 

Again, the page switches to a ListView in the Snapped state: 


© Group Title: 2 
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Notice that the Button has changed appearance as well. StandardStyles.xaml has a 
SnappedBackButtonStyle as well as a PortraitBackButtonStyle. Here’s the portrait view: 


® Group Title: 

Group Subtitle: 2 
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From either this GroupedltemsPoge or the GroupDetailPage you can navigate to a page for the 
individual item: 


® Group Title: 2 

Item Title: 3 


Item Subtitle: 3 



Item Content Curabitur class aliquam vestibulum nam curae maecenas sed integer eras 
phasellus suspendisse quisque donee dis praesent accumsan bibendum pellentesque 
condimentum adipiscing etiam consequat vivamus dictumst aliquam duis convallis 


scelerisque est parturient ullamcorper aliquet fusee suspendisse nunc hac eleifend amet 
blandit facilisi condimentum commodo scelerisque faucibus aenean ullamcorper ante 
mauris dignissim consectetuer nullam lorem vestibulum habitant conubia elementum 
pellentesque morbi facilisis arcu sollicitudin diam cubilia aptent vestibulum auctor eget 
dapibus pellentesque inceptos leo egestas interdum nulla coosectetuer suspendisse 
adipiscing pellentesque proin lobortis sollicitudin augue elit mus congue fermentum 
parturient fringilla euismod feugiat 

Curabitur class aliquam vestibulum nam curae maecenas sed integer eras phasellus 
suspendisse quisque donee dis praesent accumsan bibendum pellentesque 
condimentum adipiscing etiam consequat vivamus dictumst aliquam duis convallis 
scelerisque est parturient ullamcorper aliquet fusee suspendisse nunc hac eleifend amet 
blandit facilisi condimentum commodo scelerisque faucibus aenean ullamcorper ante 
mauris dignissim consectetuer nullam lorem vestibulum habitant conubia elementum 
pellentesque morbi facilisis arcu sollicitudin diam cubilia aptent vestibulum auctor eget 
dapibus pellentesque inceptos leo egestas interdum nulla consectetuer suspendisse 
adipiscing pellentesque proin lobortis sollicitudin augue elit mus congue fermentum 
parturient fringilla euismod feugiat 

Curabitur class aliquam vestibulum nam curae maecenas sed integer eras phasellus 
suspendisse quisque donee dis praesent accumsan bibendum pellentesque 
condimentum adipiscing etiam consequat vivamus dictumst aliquam duis convallis 
scelerisque est parturient ullamcorper aliquet fusee suspendisse nunc hac eleifend amet 
blandit facilisi condimentum commodo scelerisque faucibus aenean ullamcorper ante 
mauris dignissim consectetuer nullam lorem vestibulum habitant conubia elementum 
pellentesque morbi facilisis arcu sollicitudin diam cubilia aptent vestibulum auctor eget 
dapibus pellentesque inceptos leo egestas interdum nulla consectetuer suspendisse 
adipiscing pellentesque proin lobortis sollicitudin augue elit mus congue fermentum 


At first it appears to be a single item; however, you can horizontally scroll to see other items in the 
same group. The bulk of the page is actually a FlipView. Each item in this FlipView is a ScrollViewer 
containing a collection of RichTextBlock elements. Ill discuss RichTextBlock in Chapter 16, "Rich Text." 
In the Grid App template, the RichTextBlock elements are generated by a RichTextColumns class that 
you’ll find in the Common folder. 

The item view also has a different appearance in the Snapped state: 



© Group Title: 2 
Item Title: 3 

Item Subtitle: 3 



Item Content Curabitur class aliquam 
vestibulum nam curae maecenas sed integer 
eras phasellus suspendisse quisque donee 
dis praesent accumsan bibendum 
pellentesque condimentum adipiscing etiam 
consequat vivamus dictumst aliquam duis 
convallis scelerisque est parturient 
ullamcorper aliquet fusee suspendisse nunc 
hac eleifend amet blandit facilisi 
condimentum commodo scelerisque 
faucibus aenean ullamcorper ante mauris 
dignissim consectetuer nullam lorem 
vestibulum habitant conubia elementum 
pellentesque morbi facilisis arcu sollicitudin 
diam cubilia aptent vestibulum auctor eget 
dapibus pellentesque inceptos leo egestas 
interdum nulla consectetuer suspendisse 
adipiscing pellentesque proin lobortis 

mill 广 ; -m rv»« ir ir\ 
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The Portrait view is also different: 


® Group Title: 2 


Item Title: 3 


Item Subtitle: 3 


Itpm C nntpnt* C nr^hitiir rl^«; •: ^linu^m \yp<rfihiil 

li im nam n ira/a 

ma*arp»nac inttaoiar rrac 

phasellus suspendisse quisque donee dis prae 



condimentum adipiscing etiam consequat viv ( 
scelerisque est parturient ullamcorper aliquet 



Disnan idCiiisi conaimenuim commooo sceier 
mauris dignissim consectetuer nullam lorem v 

SrrrfWilifi 

acitcaii uiioiiilui pci anic 

tant conubia elementum 



pellentesque morbi facilisis arcu sollicitudin diam cubilia aptent vestibulum auctor ec 
dapibus pellentesque inceptos leo egestas interdum nulla consectetuer suspendisse 
adipiscing pellentesque proin lobortis sollicitudin augue elit mus congue fermentum 
parturient fringilla euismod feugiat 

Curabitur class aliquam vestibulum nam curae maecenas sed integer eras phasellus 
suspendisse quisque donee dis praesent accumsan bibendum pellentesque 
condimentum adipiscing etiam consequat vivamus dictumst aliquam duis convallis 
scelerisque est parturient ullamcorper aliquet fusee suspendisse nunc hac eleifend an 
blandit facilisi condimentum commodo scelerisque faucibus aenean ullamcorper ante 
mauris dignissim consectetuer nullam lorem vestibulum habitant conubia elementum 
pellentesque morbi facilisis arcu sollicitudin diam cubilia aptent vestibulum auctor egc 
dapibus pellentesque inceptos leo egestas interdum nulla consectetuer suspendisse 
adipiscing pellentesque proin lobortis sollicitudin augue elit mus congue fermentum 
parturient fringilla euismod feugiat 


mSm 


condimentum adipiscing etiam consequat vivamus dictumst aliquam duis convallis 
scelerisque est parturient ullamcorper aliquet fusee suspendisse nunc hac eleifend amet 
blandit facilisi condimentum commodo scelerisque faucibus aenean ullamcorper ante 
mauris dignissim consectetuer nullam lorem vestibulum habitant conubia elementum 
pellentesque morbi facilisis arcu sollicitudin diam cubilia aptent vestibulum auctor eget 
dapibus pellentesque inceptos leo egestas interdum nulla consectetuer suspendisse 
adipiscing pellentesque proin lobortis sollicitudin augue elit mus congue fermentum 
parturient fringilla euismod feugiat 


Although 111 continue to use the Blank App and Blank Page templates in the projects in this book, 
I’ll implement some of the features from the more sophisticated templates in a simplified and (I hope) 
more comprehensible manner. 


View Models and Collections 


As you saw in Chapter 11, "The Three Templates," the Colors class provides a convenient source of 
objects to display in an ItemsControl and ListBox. However, when graduating to the Grid View and 
ListView controls, it’s good to move to example data that is a little more sophisticated and a little 
more real. 
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For that purpose, the http://www.charlespetzold.com/Students directory of my website contains a 
file named students.xml that contains information on 69 students of a high school. The directory also 
contains lovely photographs of these students that originated in high school yearbooks from El Paso, 
Texas, for the years 1912 through 1914. The yearbooks are in the public domain, and they were digi¬ 
tized by the El Paso Public Library and made available to the public at http://www.elpasotexos.gov/ 
Hbrary/ourlibraries/mainjibrary/yearbooks/yearbooks.asp. 

The EIPasoHighSchool project is a library that accesses this XML file and constructs a view model 
to make the information available to applications. The following Student class represents a single stu¬ 
dent. Notice that the class implements INotifyPropertyChonged to make it suitable for data bindings: 


Project: EIPasoHighSchool | File: Student.es 

using System.ComponentModel; 

using System.Runtime.Compi1erServices; 


namespace EIPasoHighSchool 
{ 

public cl ass Student : INotifyPropertyChanged 
{ 

string full Name, firstName, middleName, lastName, sex, photoFi1ename; 
double gradePointAverage; 

public event PropertyChangedEventHandler PropertyChanged; 

public string Full Name 
{ 

set { SetProperty<stri ng>(ref full Name, value); } 
get { return full Name; } 

} 

public string FirstName 
{ 

set { SetProperty<stri ng>(ref firstName, value); } 
get { return firstName; } 

} 

public string MiddleName 
{ 

set { SetProperty<stri ng>(ref middleName, value); } 
get { return middleName; } 

} 


public string LastName 
{ 

set { SetProperty<stri ng>(ref lastName, value); } 
get { return lastName; } 

} 

public string Sex 
{ 

set { SetProperty<stri ng>(ref sex, value); } 
get { return sex; } 

} 
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public string PhotoFi1ename 

{ 

set { SetProperty<stri ng>(ref photoFi1ename, value); } 
get { return photoFi1ename; } 

} 

public double GradePointAverage 

{ 

set { SetPrope rty<double>( ref gradePointAverage, value); } 
get { return gradePointAverage; } 

} 


protected 

{ 


bool SetProperty<T>(ref T storage, T value, 

[Cal 1erMemberName] string propertyName = null) 


if (object .Equals(storage, value)) 
return false; 


storage = value; 

OnPropertyChanged(propertyName); 
return true; 


} 


protected void OnPropertyChanged(stri ng propertyName) 

{ 

if (PropertyChanged != null) 

PropertyChanged(thi s , new PropertyChangedEventArgs (propertyName)); 

} 

} 


The StudentBody class shown next also implements INotifyPropertyChongecJ. The class contains the 
name of the school and an ObservableCollection of type Student to store all the Student objects: 

Project: EIPasoHighSchool I File: StudentBody.es 

using System.Col 1ections.ObjectModel; 

using System.ComponentModel; 

using System.Runtime.Compi1erServices; 

namespace EIPasoHighSchool 

{ 

public cl ass StudentBody : INotifyPropertyChanged 

{ 

string school; 

ObservableCol1ection<Student> students = new ObservableCol1ecti on<Student>() ; 

public event PropertyChangedEventHandler PropertyChanged; 

public string School 

{ 

set { SetProperty<stri ng>(ref school, value); } 
get { return school; } 

} 

public ObservableCol1ection<Student> Students 
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} 


set { SetProperty<Observabl eCol 1 ection<Student»(ref students, value); } 
get { return students; } 


protected bool SetProperty<T>(ref T storage, T value, 

[Cal 1erMemberName] string propertyName 


{ 


if (object■ Equals(storage ， value)) 
return false; 


= null) 


storage = value; 

OnPropertyChanged(propertyName); 
return true; 


protected void OnPropertyChanged(stri ng propertyName) 


if (PropertyChanged != null) 

PropertyChanged(thi s , new PropertyChangedEventArgs (propertyName)) 


} 


ObservableCollection implements the INotifyCollectionChanged interface, which defines a 
CollectionChanged event. ObservableCollection fires this event whenever an item is added to 
or removed from the collection or existing items are reordered. When you set an object to the 
ItemsSource property of an items control, the control checks whether the object implements 
INotifyCollectionChanged. If so, it attaches a handler for the CollectionChanged event and modifies its 
display when items are added, removed, or reordered. 

The student.xml file on my website looks like this: 


File: http://www.charlespetzold.com/Students/students.xml (excerpt) 

<?xml version="1.0" encodi ng="utf-8" ?> 

〈StudentBody xml ns:xsd= n http://www.w3.org/2001/XMLSchema" 

xml ns:xsi=" http://www.w3.org/2001/XMLSchema-instance ”〉 
<School>El Paso High School</School >-<Students> 

<Student> 

<Ful1 Name>Adki ns Bowden</Ful 1Name> 

<Fi rstName>Adkins</Fi rstName> 

<MiddleName/> 

<LastName>Bowden</LastName> 

<Sex>Male</Sex> 

<PhotoFilename> 

http://www.charlespetzold.com/Students/AdkinsBowden.png 
</PhotoFi1ename> 

<GradePointAverage>2.71</GradePointAverage> 

</Student> 

<Student> 

<Ful1Name>Al fred B1 ack</Ful 1Name> 

<FirstName>Al fred</Fi rstName> 

<MiddleName/> 

<LastName>Bl ack</LastName> 

<Sex>Male</Sex> 

<PhotoFilename> 

http://www.charlespetzold.com/Students/AlfredBlack, png 
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</PhotoFi1ename> 

<GradePointAverage>2 . 87</GradePointAverage> 

</Student> 

<Student> 

<Ful1 Name>Alice Bi shop</Ful1 Name> 

<Fi rstName>Al i ce</Fi rstName> 

<MiddleName/> 

<LastName>Bishop</LastName> 

<Sex>Female</Sex> 

<PhotoFilename> 

http://www.charlespetzold.com/Students/Al i ceBi shop.png 
</PhotoFi1ename> 

<GradePointAverage>3 . 68</GradePoi ntAverage> 

</Student> 

<Student> 

<Ful1 Name>Wi 11iam Sheley Warnock</Ful 1Name> 

<Fi rstName>Wi lli am</Fi rstName> 

<Middl eName>Sheley</Mi ddleName> 

<LastName>Warnocl«/LastName> 

<Sex>Male</Sex> 

<PhotoFilename> 

http://www.charlespetzold.com/Students/Willi amSheleyWarnock.png 
</PhotoFi1ename> 

<GradePointAverage>l.82</GradePointAverage> 

</Student> 

</Students> 

</StudentBody> 

The Student and StudentBody element tags conveniently correspond to the Student and 
StudentBody classes you’ve just seen. I created this XML file by using .NET serialization with 
the XmlSerializer class, and it can be deserialized in the same way. This is the purpose of the 
StudentBody Presenter class, which again implements I No tifyProp ertyChanged but has just one 
property of type StudentBody: 

Project: EIPasoHighSchool | File: StudentBodyPresenter.es (excerpt) 

public class StudentBodyPresenter : INotifyPropertyChanged 

{ 

StudentBody StudentBody; 

Random rand = new RandomO; 

Window currentWindow = Window. Current; 

public event PropertyChangedEventHandler PropertyChanged; 

public StudentBodyPresenter() 

{ 

// Download XML file 

HttpClient httpClient = new HttpCli ent() ; 

Task<stri ng> task = 

httpClient.GetStri ngAsync("http: //www.charlespetzold.com/Students/students.xml ") ; 
task.ContinueWith(GetStringCompleted); 

} 

async void GetStringCompl eted(Task<stri ng> task) 
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if (task.Exception == null && !task.IsCanceled) 

{ 

string xml = task.Result; 

// Deserialize XML 

StringReader reader = new Stri ngReader(xml ); 

Xml Serializer serializer = new Xml Serial izer(typeof (StudentBody)) ; 

await currentWindow.Dispatcher.RunAsync(CoreDi spatcherPriori ty. Normal,()=> 

{ 

this .StudentBody = serializer.Deserialize(reader) as StudentBody; 

// Set a timer for random changes 
DispatcherTimer timer = new DispatcherTimer 
{ 

Interval = TimeSpan . FromMiHi seconds(100) 

}； 

timer.Tick += OnTimerTick; 
timer.Start(); 

}); 

} 

} 


public StudentBody StudentBody 

{ 

set { SetProperty<StudentBody>(ref StudentBody, value); } 
get { return StudentBody; } 

} 

// Mimic changing grade point averages 
void OnTimerTick (object sender, object args) 

{ 

int index = rand.Next(StudentBody.Students.Count); 

Student student = this. StudentBody.Students[index]; 
double factor = 1 + (rand.NextDouble() - 0.5) / 5; 
student.GradePointAverage = 

Math. Max(0.0, 

Math.Min(5 .0, (int) (100 * factor * student.GradePointAverage) / 100.0)); 

} 

protected bool SetProperty<T>(ref T storage, T value, 

[Cal 1 erMemberName] string propertyName = null) 

{ 

if (object .Equals(storage, value)) 
return false; 

storage = value; 

OnPropertyChanged(propertyName); 
return true; 

} 

protected void OnPropertyChanged(stri ng propertyName) 

{ 

if (PropertyChanged != null) 

PropertyChanged(thi s , new PropertyChangedEventArgs (propertyName)); 

} 


} 
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This class caused me some problems. I wanted to initiate the loading and deserializing of the XML 
file from the class’s constructor, but constructors cannot be declared as osync, so I needed an explicit 
continuation handler instead. However, the continuation handler does not run in the user-interface 
thread. This is a problem because this method needs to set the StudentBody property, which causes a 
PropertyChanged event to be fired and possibly an updating of a binding on a user-interface object. 
The class needs to set the StudentBody property in the user-interface thread using a CoreDispatcher, 
but where does this CoreDispatcher object come from? The class has no access to objects created in 
the user-interface thread, which are the usual sources of CoreDispatcher. 

Fortunately, the Window object has a Dispatcher property, and it’s easy to get the current 
window through the Window.Current static property. The StudentBodyPresenter class also sets a 
DispatcherTimer for simulating real-time changes in the students’ grade point averages to give the 
PropertyChanged event a little workout. 

Let’s create a new solution and project named DisplayHighSchoolStudents. To this solution add 
the existing EIPasoHighSchool project. In the References section of the DisplayHighSchoolStudents 
project, set a reference to the EIPasoHighSchool project, and in the MainPage.xaml file, create a new 
XML namespace prefix: 

xml ns : el paso="usi ng : ElPasoHighSchool" 

You can then instantiate the StudentBodyPresenter class in the Resources section of MainPage.xaml: 


<Page.Resources 〉 

<elpaso : StudentBodyPresenter x: Key="presenter" /> 

</Page.Resources 〉 

And now you can begin experimenting with accessing items from this view model. 


For example, the markup 

<Grid Background:'' {StaticResource ApplicationPageBackgroundThemeBrush}"> 
<TextBlock Text="{Binding Source={Stati cResource presenter}}" 
FontSize="24" /> 

</Crid> 


causes the TextBlock to display the fully qualified class name "EIPasoHighSchool.StudentBodyPre¬ 
senter’’. The markup 

<TextBlock Text="{Bi nding Source={Stati cResource presenter} , 

Pat h=StudentBody}" 

FontSize="24" /> 

displays the fully qualified class name "EIPasoHighSchool.StudentBody”. 
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Try going another property deeper, like so: 


<TextBlock Text="{Bi nding Source={Stati cResource presenter} , 

Path=StudentBody. School}" 

FontSize="24" /> 

Now you get some real data: the value of the School property or "El Paso High School”. 

The other property in StudentBody is Students. Try that in the markup: 

<TextBlock Text="{Bi nding Source={Stati cResource presenter} , 

Path=StudentBody. Students}" 

FontSize="24" /> 

The displayed text is another fully qualified class name, this one quite lengthy: "System-Collections 
•ObjectModel.ObservableCollection'l[EIPasoHighSchool. Student:]". 

However, you can index the Students property in the markup: 

<TextBlock Text="{Bi nding Source={Stati cResource presenter} , 

Path=StudentBody. Students [23] }" 

FontSize="24" /> 

The result is another fully qualified class name, "EIPasoHighSchool.Student", but now weYe at the 
point where we can see actual properties of that class. 


One property of the Student class is Full Nome, so try this: 

<TextBlock Text="{Bi nding Source={Stati cResource presenter} , 

Path=StudentBody. Students [23] .Full Name}" 

FontSize="24" /> 

The result is the student’s name: "Elizabeth Barnes”. 

Try replacing that TextBlock with an Image element, and reference the PhotoFilenome property of 
Student: 

<Grid Background=” {StaticResource ApplicationPageBackgroundThemeBrush}"> 

<Image Source="{Bi nding Source={Stati cResource presenter} , 

Path=StudentBody. Students [23] .PhotoFilename}" /> 

</Grid> 
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And there she is: 



Now let’s try replacing that Image element with a Grid View with the ItemsSource property set to 
the Students property of StudentBody: 

<Crid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

<GridView ItemsSource="{Bi nding Source={Stati cResource presenter} , 

Path=StudentBody. Students}" /> 

</Crid> 

The result is a display of Student objects: 


EIPasoHighSchooLStudent EIPasoHighSchooKStudent ElPasoHighSchooLStudent EIPasoHighSchooLStudent EIPasoHighSchool.Student 

EIPasoHighSchooLStudent EIPasoHighSchooLStudent EIPasoHighSchooLStudent EIPasoHighSchooLStudent EIPasoHighSchooLStudent 

EIPasoHighSchooLStudent EIPasoHighSchool.Student EIPasoHighSchooLStudent EIPasoHighSchool.Student EIPasoHighSchooLStudent 

EIPasoHighSchooLStudent EIPasoHighSchooLStudent EIPasoHighSchooLStudent EIPasoHighSchooLStudent EIPasoHighSchooLStudent 

EIPasoHighSchool.Student EIPasoHighSchool.Student EIPasoHighSchool.Student EIPasoHighSchool.Student EIPasoHighSchool.Student 

EIPasoHighSchooLStudent EIPasoHighSchooLStudent EIPasoHighSchooLStudent EIPasoHighSchooLStudent EIPasoHighSchooLStudent 

EIPasoHighSchooLStudent EIPasoHighSchooLStudent EIPasoHighSchooLStudent EIPasoHighSchooLStudent EIPasoHighSchooLStudent 

EIPasoHighSchooLStudent EIPasoHighSchool.Student EIPasoHighSchooLStudent EIPasoHighSchool.Student EIPasoHighSchooLStudent 

EIPasoHighSchooLStudent EIPasoHighSchooLStudent EIPasoHighSchooLStudent EIPasoHighSchooLStudent EIPasoHighSchooLStudent 

EIPasoHighSchool.Student EIPasoHighSchool.Student EIPasoHighSchool.Student EIPasoHighSchool.Student 

EIPasoHighSchooLStudent EIPasoHighSchooLStudent EIPasoHighSchooLStudent EIPasoHighSchooLStudent 

EIPasoHighSchooLStudent EIPasoHighSchooLStudent EIPasoHighSchooLStudent EIPasoHighSchooLStudent 

EIPasoHighSchooLStudent EIPasoHighSchool.Student EIPasoHighSchooLStudent EIPasoHighSchool.Student 

EIPasoHighSchooLStudent EIPasoHighSchooLStudent EIPasoHighSchooLStudent EIPasoHighSchool.Student 

EIPasoHighSchool.Student EIPasoHighSchool.Student EIPasoHighSchool.Student EIPasoHighSchool.Student 


596 PART Elementals 







Although the Student objects are shown only as fully qualified class names, you can still detect some 
workings of the GridView. The display bounces a bit if you try to scroll it, and you can select individual 
items: 


EIPasoHighSchool.Student EIPasoHighSchool^tudent EIPasoHighSchooLStudent EIPasoHighSchooLStudent EIPasoHighSchool.Student 

EIPasoHighSchool.Student EIPasoHighSchooLStudent EIPasoHighSchooLStudent EIPasoHighSchool.Student EIPasoHighSchool.Student 

EIPasoHighSchool.Student EIPasoHighSchool.Student EIPasoHighSchool.Student EIPasoHighSchool.Student EIPasoHighSchool.Student 

EIPasoHighSchooLStudent EIPasoHighSchooLStudent EIPasoHighSchooLStudent EIPasoHighSchooLStudent EIPasoHighSchooLStudent 

EIPasoHighSchool.Student EIPasoHighSchool.Student EIPasoHighSchooLStudent EIPasoHighSchooLStudent EIPasoHighSchooLStudent 

EIPasoHighSchool.Student EIPasoHighSchool^tudent ilPasoHighSchooLStua^ EIPasoHighSchooLStudent EIPasoHighSchool.Student 

EIPasoHighSchool.Student EIPasoHighSchooLStudent EIPasoHighSchooLStudent EIPasoHighSchool.Student EIPasoHighSchool.Student 

EIPasoHighSchool.Student EIPasoHighSchool.Student EIPasoHighSchool.Student EIPasoHighSchool.Student EIPasoHighSchool.Student 

EIPasoHighSchooLStudent EIPasoHighSchooLStudent EIPasoHighSchooLStudent EIPasoHighSchool.Student EIPasoHighSchooLStudent 

EIPasoHighSchool.Student EIPasoHighSchool.Student EIPasoHighSchool.Student EIPasoHighSchool.Student 

EIPasoHighSchooLStudent EIPasoHighSchool^tudent EIPasoHighSchooLStudent EIPasoHighSchooLStudent 

EIPasoHighSchool.Student EIPasoHighSchooLStudent EIPasoHighSchooLStudent EIPasoHighSchool.Student 

EIPasoHighSchool.Student EIPasoHighSchool.Student EIPasoHighSchool.Student EIPasoHighSchool.Student 

EIPasoHighSchooLStudent EIPasoHighSchooLStudent EIPasoHighSchooLStudent EIPasoHighSchool.Student 

EIPasoHighSchool.Student EIPasoHighSchool.Student EIPasoHighSchool.Student EIPasoHighSchool.Student 


Let’s simplify the Binding by moving part of it to the Grid as a DataContext property: 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}" 
DataContext="{Bi nding Source={Stati cResource presenter} , 

Path=StudentBody}"> 

<Grid.RowDefiniti ons> 

〈RowDefinition Hei ght="Auto" /> 

〈RowDefinition Height:"*" /> 

</Grid.RowDefiniti ons> 


〈TextBlock Text="{Binding School }" 

Grid.Row="0" 

Styl e="{StaticResource PageHeaderTextStyl e}" /> 

〈GridView ItemsSource="{Bi nding Students}" 

Grid.Row="l" /> 

</Grid> 

Anything within that Grid can now access properties of the StudentBody class with very simple 
bindings. A TextBlock in the Grid references the School property. 


Now all that's necessary is to add a DotoTemplote to the GridView for the Student items: 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}" 
DataContext="{Bi nding Source={Stati cResource presenter} , 

Path=StudentBody}"> 

<Grid.RowDefiniti ons> 

〈RowDefinition Hei ght="Auto" /> 

〈RowDefinition Height:"*" /> 

</Grid.RowDefiniti ons> 
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<TextBlock Text="{Binding School }" 

Grid.Row="0" 

Styl e="{StaticResource PageHeaderTextStyl e}" /> 


<GridView ItemsSource="{Bi nding Students}" 

Gn'd.Row="l"> 

<GridView.ItemTemplate> 

<DataTemplate> 

〈Border BorderBrush="{Stati cResource ApplicationForegroundThemeBrush}" 
BorderThi ckness="l"> 


〈Grid Height="120"> 

<Grid.ColumnDefinitions> 

<ColumnDefinition Width="80" /> 
<ColumnDefinition Width="200" /> 
</Grid.ColumnDefinitions> 


<Image Source="{Bi nding PhotoFi1ename} 
Grid.Column="0" /> 


〈TextBlock Text="{Binding Full Name} 
Grid.Column="l" 


</Gri d> 
</Border> 
</DataTemplate> 

</GridView.ItemTemplate> 
</GridView> 

</Grid> 


VerticalAli gnment="Center" 
Margin="5 0" /> 


And here they are, horizontally scrollable, of course: 
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ListViewBose differentiates between clicking an item as if it were a button and selecting an item. 
Much of the selection support is inherited from Selector and is similar to ListBox. By default, when you 
tap an item, that item is selected. The item is displayed with a colored background and a checkmark, 
and the control fires a SelectionChongecJ event. 

By default, item clicking is disabled, but you can enable this feature by setting a property and an 
event handler: 


<GridView ItemsSource="{Bi nding Students}" 

Grid.Row="l" 

IsItemClickEnabl ed="T rue" 

ItemCli ck="OnGri dViewItemClick"> 

Now when you tap an item, the item is not selected and instead an ItemClick event is fired. The event 
arguments to the ItemClick handler include the item, in this case an object of type Student. 

However, the user can still select and unselect items by swiping them or right-clicking them. You 
can turn off selection entirely by setting the Selection Mode to None: 

<GridView ItemsSource="{Bi nding Students}" 

Grid.Row="l" 

Selecti onMode="None" 

IsItemClickEnabl ed="T rue" 

ItemCli ck="OnGri dViewItemClick"> 


You can also set SelectionMode to Multiple, but obviously you don’t want to implement selection at 
all if the program can’t do anything with selected items. 

Even when SelectionMode is set to None, you can still swipe items. The swiped item moves, 
but nothing is selected. You probably want to keep swiping in effect if you're going to implement 
dragging and reordering with the AllowDrop and ConRecorderltems properties: 

<GridView ItemsSource="{Bi nding Students}" 

Grid.Row= ,, l" 

SelectionMode=" None" 

AllowDrop="True" 

CanReorderItems="True" 

IsItemClickEnabl ed="T rue" 

ItemCli ck="OnGri dViewItemClick"> 

However, if you’re not going to allow selection or reordering, it’s probably best to disable swiping 
entirely: 

<GridView ItemsSource="{Bi nding Students}" 

Grid.Row="l" 

Selecti onMode="None" 

IsSwipeEnabl ed="Fal se" 

IsItemClickEnabl ed="T rue" 

ItemCli ck="OnGri dViewItemCl ick" /> 
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In the complete DisplayHighSchoolStudents project, I have attempted to emulate the general 
layout of the Visual Studio standard Grid App while still using Blank App. The code-behind file for 
Main Page uses the SizeChangecJ handler to set a visual state based on the current view: 


Project: DisplayHighSchoolStudents | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

public MainPageO 

{ 

this .InitializeComponent(); 

SizeChanged += OnPageSizeChanged; 

} 


void OnPageSizeChanged (object sender, SizeChangedEventArgs args) 

{ 

VisualStateManager .GoToState(thi s , ApplicationView .Value.ToString(), true) ; 

} 


The XAML file has a GridView for all view states except Snapped, and a ListView for Snapped. The 
two controls share a DotoTemplate for displaying the items. This is defined in the Resources section of 
the XAML file along with the view model: 


Project: DisplayHighSchoolStudents | File: MainPage.xaml (excerpt) 

<Page … > 

<Page.Resources 〉 

<elpaso : StudentBodyPresenter x : Key="presenter" /> 

<DataTemplate x: Key="studentTempl ate"> 

〈Border Hei ght="120" 

Width="280"> 

<Grid> 

<Grid.RowDefinitions> 

<RowDefinition Height:"*" /> 

〈RowDefinition Height="*" /> 

</Grid.RowDefinitions> 

<Grid.ColumnDefinitions> 

<ColumnDefinition Wi dth="Auto" /> 

<ColumnDefinition Width="*" /> 

</Grid.ColumnDefinitions> 

〈Image Grid. Row="0" Grid.Col umn="0" Grid.RowSpan="2" 
Source="{Bi nding PhotoFi1ename}" 

Height="120" 

Margin="5" /> 

〈TextBlock Text="{Bi nding FullName}" 

Grid. Row= M 0" Grid.Col umn="l" 

VerticalAli gnment="Center" 

Margin="5 0" /> 

<StackPanel Grid.Row="l" Grid.Column="l" 
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Orientati on="Hori zontal" 

VerticalAli gnment="Center" 

Margin="5 0"> 

<TextBlock Text="GPA =&#x00A0;" /> 

<TextBlock Text="{Binding GradePointAverage}" /> 
</StackPanel> 

</Grid> 

</Border> 

</DataTemplate> 

</Page.Resources> 


</Page> 


Because this DatoTemplote is shared between the Grid View and ListView, and because the ListView 
is used in Snapped mode, and because Snapped mode always implies a 320-unit width, a template 
defined for Snapped needs to be narrower than 320 units. Of course, it’s always possible to use 
different item templates for the two controls as the Grid App template does. 

The page is divided into two rows, with the top row dedicated to an invisible Back button and 
page title: 


Project: DisplayHighSchoolStudents | File: MainPage.xaml (excerpt) 

<Page … > 


<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}" 
DataContext="{Bi nding Source={Stati cResource presenter} , 

Path=StudentBody}"> 

<Grid.RowDefinitions> 

〈RowDefinition Height="140" /> 

〈RowDefinition Height="*" /> 

</Grid.RowDefiniti ons> 

<Grid Grid. Row="0"> 

<Grid.ColumnDefini ti ons> 

<ColumnDefinition Wi dth="Auto" /> 

<ColumnDefinition Width="*" /> 

</Grid.ColumnDefini ti ons> 

〈Button Name="backButton" 

Grid.Column="0" 

Style="{Stati cResource BackButtonStyle}" 
IsEnabled="False" /> 

<TextBlock Name="pageTi tle" 

Text="{Bi nding School }" 

Grid.Col umn="l" 

Style="{Stati cResource PageHeaderTextStyle}" /> 

</Grid> 

</Grid> 

</Page> 
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Notice that the Button is disabled because this is the main page. The standard style for this button 
hides the button entirely when it’s disabled. The Text Block is also based on a standard style, and it has 
a binding to the School property. 

The second row of the Grid contains both the GridView and ListView, but the ListView has its 
Visibility property set to Collapsed: 


Project: DisplayHighSchoolStudents | File: MainPage.xaml (excerpt) 

<Page … > 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}" 
DataContext="{Bi nding Source={Stati cResource presenter} , 

Path=StudentBody}"> 

<Grid.RowDefiniti ons> 

<RowDefinition Height="140" /> 

< RowDefi nit ion Height:' 1 *" /> 

</Grid.RowDefinitions> 

<GridView Name="gri dView" 

Grid.Row="l" 

ItemsSource="{Bi nding Students}" 

Padding="116 0 40 46" 

Sel ectionMode="None" 

IsSwipeEnabl ed="Fal se" 

IsItemClickEnabled="T rue" 

ItemCli ck="0nGri dViewItemCl i ck" 

ItemTemplate="{Stati cResource studentTemplate}" /> 

〈ListView Name="l istView" 

Grid.Row="l" 

ItemsSource="{Bi nding Students}" 

Vi sibi1i ty="Col1 apsed" 

Sel ectionMode="None" 

IsSwipeEnabl ed="Fal se" 

IsItemClickEnabl ed="T rue" 

ItemCli ck="0nGri dViewItemClick" 

ItemTempl ate="{StaticResource studentTemplate}" /> 


</Gri d> 
</Page> 


Obviously, the GridView and ListView share a bunch of properties. These could be defined in a Style 
with a TargetType of ListViewBase. Selection has been disabled, but both controls have an Item Click 
event set to a handler in the code-behind file. 


Finally, Main Page has a section for Visual State Manager markup. The primary purpose is to hide 
the GridView and show the ListView when the application is in the Snapped state: 


Project: DisplayHighSchoolStudents | File: MainPage.xaml (excerpt) 

<Page … > 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}" 
DataContext="{Bi nding Source={Stati cResource presenter} , 

Path=StudentBody}"> 
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<VisualStateManager.VisualStateGroups> 

<VisualStateGroup x : Name="Appl icationViewStates"> 

<VisualState x:Name="Ful IScreenLandscape" /> 

〈VisualState x:Name="Filled" /> 

<VisualState x:Name="Ful1 ScreenPortrait"> 

<Storyboard> 

<ObjectAnimationllsi ngKeyFrames Storyboard .TargetName="backButton" 

Storyboard.Target Property="Style"> 
<DiscreteObjectKeyFrame KeyTime="0" 

Val ue="{StaticResource PortraitBackButtonStyl e}" /> 
</Obj ectAni mati onllsi ngKeyFrames> 


<ObjectAnimati onllsi ngKeyFrames Storyboard .TargetName="gri dVi ew" 

Storyboard.TargetPrope rty="Paddi ng"> 
<DiscreteObjectKeyFrame KeyTime="0" Value="96 0 10 56" /> 

</0bj ectAni mati onllsi ngKeyFrames> 

</Storyboard> 

</VisualState> 


<VisualState x:Name="Snapped"> 

<Storyboard> 

<0bjectAni mati onllsi ngKeyFrames Storyboard .TargetName="gri dVi ew" 

Storyboard.TargetProperty="Vi si bi 1 i ty"> 
<DiscreteObjectKeyFrame KeyTime="0" Val ue="Col lapsed" /> 

</0bjectAnimationUsingKeyFrames> 


<0bjectAnimationUsingKeyFrames Storyboard.TargetName="l istView" 

Storyboard.TargetProperty="Vi sibi1ity"> 
<DiscreteObjectKeyFrame KeyTime="0" Val ue="Vi sible" /> 

</0bjectAnimationUsingKeyFrames> 


<0bjectAnimationUsingKeyFrames Storyboard .TargetName="backButton" 

Storyboard.TargetProperty=" Style"> 
<DiscreteObjectKeyFrame KeyTime="0" 

Val ue="{StaticResource SnappedBackButtonStyle}" /> 
</0bjectAnimationUsingKeyFrames> 


<0bjectAnimationUsingKeyFrames Storyboard .TargetName="pageTi tie" 

Storyboard.TargetProperty=" Style"> 

<DiscreteObjectKeyFrame KeyTime="0" 

Val ue="{StaticResource SnappedPageHeaderTextStyl e}" /> 
</0bjectAnimationUsingKeyFrames> 

</Storyboard> 

</VisualState> 

</VisualStateGroup> 

</VisualStateManager.VisualStateGroups> 

</Gri d> 

</Page> 

In addition to swapping the visibility of the GridView and ListView, this Visual State Manager section 
also changes button and title styles and the GridView padding. 
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Here’s the program running normally: 


El Paso High School 



It won’t take long to see the grade point averages changing. 

In Snapped mode, the program switches to a ListView with a smaller title: 
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In portrait mode, the extra space at the sides closes up a bit: 



Whenever an item is clicked, the Grid View or ListView fires an Item Click event. This initiates 
navigation to a Page derivative of type StudentPoge, passing to it the Clickedltem property of the 
event arguments, which is an object of type Student: 


Project: DisplayHighSchoolStudents | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 
{ 

void OnCridViewItemCli ck(object sender, ItemClickEventArgs args) 
{ 

this. Frame.Navi gate(typeof (StudentPage) , args.Clickedltem); 

} 

} 
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In the OnNavigatedTo override in StudentPage, this Student object is set to the DataContext of the 
page: 

Project: DisplayHighSchoolStudents | File: StudentPage.xaml.es (excerpt) 

public sealed partial class StudentPage : Page 

{ 

public StudentPageO 

{ 

this .InitializeComponent(); 

SizeChanged += OnPageSizeChanged; 

} 

void OnPageSizeChanged (object sender, SizeChangedEventArgs args) 

{ 

VisualStateManager .GoToState(thi s , ApplicationView. Value.ToString(), true) ; 

} 

protected override void OnNavigatedTo(Navi gationEventArgs args) 

{ 

this .DataContext = args.Parameter; 
base. OnNavigatedTo(args); 

} 

void OnBackButtonCli ck(object sender, RoutedEventArgs args) 

{ 

this .Frame.GoBack(); 

} 

} 

Also notice the call to VisuolStateManoger.GoToStote as well as a Click handler to go back to Main- 
Poge. 

The StudentPage.xaml file simply displays a couple properties of the Student class: 

Project: DisplayHighSchoolStudents | File: StudentPage.xaml (excerpt) 

<Page … 

Name="page" 

FontSi ze="24"> 


<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Grid.RowDefinitions> 

<RowDefinition Height="140" /> 

〈RowDefinition Height:"*" /> 

</Grid.RowDefinitions> 

〈Grid Grid. Row="0"> 

<Grid.ColumnDefinitions> 

<ColumnDefinition Wi dth="Auto" /> 

<ColumnDefinition Width="*" /> 

</Grid.ColumnDefiniti ons> 

〈Button Name="backButton" 

Grid.Col umn="0" 

Style="{StaticResource BackButtonStyle}" 

IsEnabl ed="{Binding El ementName=page , Path=Frame .CanGoBack} 
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Cli ck="OnBackButtonCl i ck" /> 


<TextBlock Name="pageTi tle" 

Text="{Bi nding FullName}" 

Grid.Col umn="l" 

Styl e="{StaticResource PageHeaderTextStyl e}" /> 

</Gri d> 

<StackPanel Grid. Row="l" 

HorizontalA1i gnment="Center"> 
clmage Source="{Bi nding PhotoFi1ename}" 

Width="240 M /> 

<TextBlock Text="{Bi nding Sex}" 

HorizontalA1i gnment="Center" 

Margin="10" /> 

<StackPanel Orientation="Hori zontal" 

HorizontalA1i gnment="Center" 

Margin="10"> 

〈TextBlock Text="GPA =&#x00A0;" /> 

<TextB1ock Text="{Bi nding GradePointAverage}" /> 
</StackPanel> 

</StackPanel> 


<VisualStateManager.VisualStateGroups> 

<VisualStateGroup x : Name="Appl icationViewStates"> 

<VisualState x:Name="Ful IScreenLandscape" /> 

〈VisualState x:Name="Filled" /> 

<VisualState x:Name="Ful1 ScreenPortrait"> 

<Storyboard> 

<ObjectAnimationllsi ngKeyFrames Storyboard .TargetName="backButton" 

Storyboard.TargetProperty=" Style"> 
<DiscreteObjectKeyFrame KeyTime="0" 

Val ue="{StaticResource PortraitBackButtonStyl e}" /> 
</Obj ectAni mati onllsi ngKeyFrames> 

</Storyboard> 

</VisualState> 


<VisualState x:Name="Snapped"> 

<Storyboard> 

<ObjectAnimationllsingKeyFrames Storyboard .TargetName="backButton" 

Storyboard.TargetProperty=" Style"> 
<DiscreteObjectKeyFrame KeyTime="0" 

Val ue="{StaticResource SnappedBackButtonStyle}" /> 
</Obj ectAni mati onllsi ngKeyFrames> 


<Obj ectAni mati onllsi ngKeyFrames Storyboard .TargetName="pageTi tie" 

Storyboard.TargetProperty=" Style"> 

<DiscreteObjectKeyFrame KeyTime="0" 

Val ue="{StaticResource SnappedPageHeaderTextStyl e}" /> 
</Obj ectAni mati onllsi ngKeyFrames> 

</Storyboard> 

</VisualState> 
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</VisualStateGroup> 

</VisualStateManager.VisualStateGroups> 
</Gri d> 

</Page> 


The Visual State Manager isn’t as elaborate as before because there’s no longer a Grid View and 
ListView to switch between. The only real issues involve styles. Here it is in portrait mode: 


® Charles Edgar Virden 



Male 

GPA = 2.66 


Grouping the Items 

To group items in a GridView or ListView, your view model needs a property of type 
ObservableCollection corresponding to the groups. The items within that collection are instances 
of a class that includes a title to identify the group and its own ObservableCollection for the 
items themselves. You’ll use this view model in conjunction with a proxy collection class called 
CollectionViewSource. 

My StudentBodyPresenter view model doesn’t have such a property, but it’s easy to create a new 
class for this purpose. 
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The GroupBySex project demonstrates how to group the students by male and female. This proj¬ 
ect supplements the view model implemented in the EIPasoHighSchool project with a couple extra 
classes. The first is called StudentGroup and has two just properties. The Title property serves as a title 
for the group, and the Students property is a collection of Student objects: 

Project: GroupBySex I File: StudentGroup.es 

public cl ass StudentGroup : INotifyPropertyChanged 

{ 

string title; 

ObservableCol1ection<Student> students = new ObservableCol1ection<Student>() ; 

public event PropertyChangedEventHandler PropertyChanged; 

public StudentGroupO 

{ 

this. Students = new ObservableCol1ection<Student>() ; 

} 

public string Title 

{ 

set { SetProperty<stri ng>(ref title, value); } 
get { return title; } 

} 

public ObservableCol1ection<Student> Students 

{ 

set { SetProperty<Observabl eCol 1 ection<Student»(ref students, value); } 
get { return students; } 

} 

protected bool SetProperty<T>(ref T storage, T value, 

[Cal 1erMemberName] string propertyName = null) 

{ 

if (object. Equals(storage, value)) 
return false; 

storage = value; 

OnPropertyChanged(propertyName); 
return true; 

} 

protected void OnPropertyChanged(stri ng propertyName) 

{ 

if (PropertyChanged != null) 

PropertyChanged(thi s , new PropertyChangedEventArgs (propertyName)); 

} 

} 


The StudentGroups class (notice the plural) has only one getable property named Groups, 
which is a collection of StudentGroup objects. It also has a set-only Source property of type 
StudentBodyPresenter that constructs the StudentGroups and StudentGroup classes. I made Source a 
property so that it can be set in XAML. 
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Project: GroupBySex | File: StudentGroups.es (excerpt) 

public class StudentGroups : INotifyPropertyChanged 


StudentBodyPresenter presenter; 

ObservableCol1ection<StudentGroup> groups = new ObservableCol1ection<StudentGroup>() 

public event PropertyChangedEventHandler PropertyChanged; 

public StudentBodyPresenter Source 

{ 

set 

{ 

if (value != null) 

{ 

presenter = value; 

presenter.PropertyChanged += OnHighSchoolPropertyChanged; 

} 

} 


void OnHighSchool PropertyChanged(object sender, PropertyChangedEventArgs args) 

{ 

if (args.PropertyName == "StudentBody" && presenter.StudentBody != null) 

{ 

this. Groups = new ObservableCol1ection<StudentGroup>() ; 
this .Groups .Add(new StudentGroup { Title = "Male" }); 
this .Groups .Add(new StudentGroup { Title = "Female" }); 

foreach (Student student in presenter.StudentBody.Students) 
if (student.Sex == "Maie") 

this .Groups[0].Students.Add(student); 

else 

this .Groups[1].Students.Add(student); 

} 


public ObservableCol1ection<StudentGroup> Groups 

{ 

set { SetProperty<Observabl eCol 1 ection<StudentGroup»(ref groups, value); } 
get { return groups; } 

} 

protected bool SetProperty<T>(ref T storage, T value, 

[Cal 1erMemberName] string propertyName = null) 

{ 

if (object .Equals(storage, value)) 
return false; 

storage = value; 

OnPropertyChanged(propertyName); 
return true; 


protected void OnPropertyChangedCstri ng propertyName) 

{ 

if (PropertyChanged != null) 

PropertyChanged(thi s , new PropertyChangedEventArgs (propertyName)); 
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When the Source property is set to an instance of StudentBodyPresenter, the set accessor attaches a 
handler for the PropertyChonged event and waits for the StudentBody property to be set and avail¬ 
able. At that time, it can create two instances of the StudentGroup class and fill those with the male 
and female students. 

For purposes of clarity I’ve kept the MainPage.xaml file to nearly the bare necessities: It has only a 
GridView, and it doesn't change the layout for different views. There is virtually no formatting aside 
from the DotaTemplote used to display each item, and I've excluded that template from this listing 
because it’s the same as in the previous program. 

The Resources section contains three classes that contribute to the collection used by the Grid View. 
The StudentBodyPresenter class is first, as in the previous project. Next, StudentGroups is instantiated 
with its Source property set to the StudentBodyPresenter instance. Finally, a CollectionViewSource 
(the proxy collection) has its Source property bound to the Groups property of StudentGroups. 

This StudentGroups object is a collection of StudentGroup objects. The CollectionViewSource needs 
to know that this source represents a collection of groups, and it also needs the property of the 
StudentGroups class that contains the actual items, in this case Students: 


Project: GroupBySex I File: MainPage.xaml (excerpt) 

<Page … > 

<Page.Resources 〉 

<elpaso : StudentBodyPresenter x: Key="presenter" /> 


<local : StudentGroups x: Key="studentGroups" 

Source="{StaticResource presenter}" /> 


<Col1ectionViewSource x : Key="col1 ectionView" 

Source="{Binding Source={StaticResource StudentGroups} , 

Path=Groups}" 

IsSourceGrouped="T rue" 

ItemsPath=" Students" /> 


<DataTemplate x: Key="studentTempl ate"> 


</DataTemplate> 
</Page.Resources 〉 


<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<GridView ItemsSource="{Bi nding Source={Stati cResource collectionView}} 
ItemTemplate="{Stati cResource studentTemplate}"> 

<!-- The Panel for the groups themselves --> 

<GridView.ItemsPanel > 

<ItemsPanelTemplate 〉 

<WrapGrid /> 

</ItemsPanelTemplate> 

</GridView.ItemsPanel> 


<GridView.GroupStyle> 

<GroupStyle> 

<!-- The content of the header --> 
<GroupStyle.HeaderTemplate> 
<DataTemplate> 
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<TextBlock Text="{Binding Title}" 

Style="{StaticResource GroupHeaderTextStyl e}" /> 

</DataTemplate> 

</GroupStyle.HeaderTemplate> 

<!-- The panel for the items within each group --> 

<GroupStyle.Panel > 

<ItemsPanelTempiate> 

<VariableSizedWrapGrid Ori entation="Verti cal" /> 

</ItemsPanelTempi ate> 

</GroupStyle.Panel > 

</GroupStyle> 

</GridView.GroupStyle> 

</GridView> 

</Gri d> 

</Page> 

The ItemsSource of the GridView is bound to that CollectionViewSource, but a few other properties 
also set here: Two panels and a DataTemplate for the header. The first of these two panels — the 
Wrap Grid set to the Items Pan el property — is the same as in the default template for GridView so that 
markup isn't required. However, it helps to show explicitly that there are two types of panel at work 
here, one for the groups and another for the items within each group. 

Here’s the result scrolled so that you can see the end of the boys and the start of the girls: 



Although I’ve been instantiating view models in the XAML file, in the general case you probably 
want to share a view model among multiple pages. A good place to instantiate a single instance 
of the view model is in the App class, and from there you can make it available to the rest of the 
application as a public property. 
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CHAPTER 13 

Touch, Etc. 


O ne of the most forward-looking aspects of the Windows Runtime is the consolidation of touch, 
mouse, and pen input. No longer is it necessary to add touch to an existing mouse-oriented 
application, or add some mouse support to a touch application. From the very beginning, the pro¬ 
grammer treats all these forms of input in a fairly interchangeable manner. In accordance with the 
Windows Runtime programming interface, I will be using the word pointer to refer to input from 
touch, mouse, and the pen (also known as the stylus) when it’s not necessary to distinguish the actual 
input device. 

The best way to handle pointer input is through the existing Windows Runtime controls. As you’ve 
seen, standard controls such as Button, Slider, ScrollViewer, and Thumb all respond to pointer input 
and use that to deliver higher-level input to your application. 

In some cases, however, the programmer needs to obtain actual pointer input, and for that 
purpose UlElement defines three different families of events: 

■ Eight low-level events beginning with the word Pointer 

■ Five higher-level events beginning with the word Manipulation 

■ Tapped, RightTapped, DoubleTapped, and Holding events 

The Control class supplements these events with virtual protected methods beginning with the word 
On and followed by the event name. 

To receive pointer input, a FrameworkElement derivative must have its IsHitTestVisible property set 
to true and its Visibility property set to Visible. A Control derivative must have its IsEnabled property 
set to true. The element must have some kind of graphical representation on the screen; a Panel 
derivative can have a Transparent background but not a null background. 


All these events are associated with the element that is underneath your finger or mouse or pen 
at the time of the event. The only exception is when a pointer has been "captured" by an element, as 
you’ll see later in this chapter. 

If you need to track individual fingers, you'll want to use the Pointer events. Each event is 
accompanied by an ID number that uniquely identifies either an individual finger or pen touching 
the screen, or the mouse or pen. In this chapter 111 demonstrate how to use Pointer events for a 
finger-paint program and a piano keyboard (unfortunately without sound). Both these programs 
obviously need to handle simultaneous input from multiple fingers. 
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In a sense, the Pointer events are the only events you need. For example, if you wish to implement 
a feature that allows the user to stretch a photograph with two fingers, you can track Pointer events 
for those two fingers and measure how far they're moving apart. But calculations of this sort are pro¬ 
vided for you in the Manipulation events. The Manipulation events consolidate multiple fingers into a 
single action, and they’re ideal for moving, stretching, pinching, and rotating visual objects. 

For some applications you might be puzzled whether to use Pointer or Manipulation events. The 
Manipulation events should probably be your first choice. Particularly if you think to yourself "\ hope 
the user’s not going to start using a second finger because I’ll just have to ignore it," you probably 
want to use the Manipulation events. Then, if the user does use two or more fingers when only one 
finger is necessary, the multiple fingers will be averaged. 

However, you’ll also discover that the Manipulation events have an intrinsic lag. A finger touching 
the screen needs to move a bit before that finger is interpreted as contributing to a manipulation. 
Manipulation events are not fired if a finger taps or holds. Sometimes this lag will be enough to 
persuade you to use the Pointer events instead. The XYSlider custom control shown in this chapter 
is a case in point. The version shown in this chapter is written with Manipulation events because it 
wouldn’t know what to do with extra fingers. But the lag time is a definite problem, so I have another 
version in Chapter 14, "Bitmaps,” that uses Pointer events. 

Pointer events are generated on a window level by the CoreWindow object, and you can derive 
Manipulation events on your own using the GestureRecognizer, but I’ll be ignoring those facilities in 
this chapter and sticking with the events defined by UlElement and the virtual methods defined by 
Control. I also won't get into information about hardware input devices available from classes in the 
Windows.Devices.Input namespace. 

Input from the pen has some special considerations involving the selection, erasing, and storage of 
pen strokes, as well as handwriting recognition. Those topics will be saved for Chapter 19, "Pen (Also 
Known as Stylus).’’ The Microsoft Surface tablet introduced in October 2012 does not support pen 
input. 

A Pointer Roadmap 

Of the eight Pointer events, five are very common. If you touch a finger to an enabled and visible 
UlElement derivative, move it, and lift it, these five Pointer events are generated in the following 
order: 

■ PointerEntered 

■ PointerPressed 

■ PointerMoved (multiple occurrences in the general case) 

■ PointerReleased 

■ PointerExited 
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A finger generates Pointer events only when the finger is touching the screen or when it has just been 
removed. There is no such thing as "hover" with touch. 

The mouse is a little different. The mouse generates PointerMoved events even without the mouse 
button pressed. Suppose you move the mouse pointer to a particular element, press the button, 
move the mouse some more, release the button, and then move the mouse off the element. The 
element generates the following series of events: 

■ PointerEntered 

■ PointerMoved (multiple) 

■ PointerPressed 

■ PointerMoved (multiple) 

■ PointerReleasecJ 

■ PointerMoved (multiple) 

■ PointerExited 

Multiple PointerPressed and PointerReleosed events can also be generated if the user presses and 
releases various mouse buttons. 

Now let’s try a pen. The element begins reacting to the pen before it actually touches the 
screen, so you’ll first see a PointerEntered event followed by PointerMoved. As the pen touches the 
screen, a PointerPressed event is generated. Move the pen, and lift it. The element continues to fire 
PointerMoved events after PointerReleosed, but it culminates with a PointerExited when the pen is 
moved farther away from the screen. It’s the same sequence of events as the mouse. 

When the user spins the mouse wheel, the following event is generated: 

■ PointerWheelChanged 

The remaining two events are rarer: 

■ PointerCoptureLost 

■ PointerConceled 

111 discuss pointer capture later in this chapter, at which time the Poin ter Cop tureL ost event becomes 
much more important. 

I have never seen a PointerConceled event even when I’ve unplugged the mouse from the 
computer, but the event exists to report an error of that sort. 

All these events are accompanied by an instance of PointerRoutedEventArgs, defined in the 
Windows.Ul.Xaml.Input namespace. (Watch out: There’s also a PointerEventArgs class in the 
Windows.Ul.Core namespace, but that’s used for the processing of pointer input on the window 
level.) As the name of this class indicates, these Pointer events are all routed events that travel up 
the visual tree. 
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PointerRoutedEventArgs defines two properties common for routed events: 

■ OriginolSource indicates the element that raised the event. 

■ Handled lets you stop further routing of the event up the visual tree. 

Lots of other information is available from the PointerRoutedEventArgs object. The following 
description covers only the highlights. The class also defines these members: 

■ Pointer property of type Pointer 

■ KeyModifiers property indicating the status of the Shift, Control, Menu (otherwise known as 
Alt), and Windows keys 

■ GetCurrentPoint method that returns a PointerPoint object 

Watch out: Already we’re dealing with classes named Pointer (defined in the 
Windows.Ul.Xoml.Input namespace) and PointerPoint (defined in Windows.Ul.Input). 

The Pointer class has just four properties: 

■ Pointer!d property is an unsigned integer identifying the mouse, or an individual finger or pen. 

■ PointerDeviceType is an enumeration value Touch, Mouse, or Pen. 

■ I sin Range is a bool that indicates whether the device is in range of the screen. 

■ IsInContoct is a bool indicating whether the finger or pen is touching the screen, or whether 
the mouse button is down. 

The PointerlcJ property is extremely important. This is what you use to track the movement of 
individual fingers. Almost always, a program that handles Pointer events will define a dictionary in 
which this Poirite rid property serves as a key. 

The GetCurrentPoint method of PointerRoutedEventArgs sounds as if it returns the current 
coordinate location of the pointer, and it does, except that it also provides a whole lot more. 

Because it’s convenient to get the location relative to a particular element, GetCurrentPoint accepts 
an argument of type UlElement. The PointerPoint object returned from this method duplicates 
some information from Pointer (the PointerlcJ and IsInContoct properties) and provides some other 
information: 

■ Position of type Point, the (x, y) location of the pointer at the time of the event 

■ Timestamp of type ulong 

■ Properties of type PointerPointProperties (defined in Windows.Ul.lnput) 

The Position property is always relative to the upper-left corner of the element you pass to the 
GetCurrentPoint method. 

PointerRoutedEventArgs also defines a method named GetlntermediatePoints that is similar to 
GetCurrentPoint except that it returns a collection of PointerPoint objects. Very often this collection 
has just one item — the same PointerPoint returned from GetCurrentPoint — but for the PointerMoved 
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event there could be more than one, particularly if the event handler isn’t very fast. I’ve particularly 
noticed GetlntermediatePoints returning multiple PointerPoint objects on the Microsoft Surface. 


The PointerPointProperties class defines 22 properties that provide detailed information about the 
event, including which mouse buttons are pressed, whether the button on the pen barrel is pressed, 
how the pen is tilted, the contact rectangle of the finger with the screen (if that's available), the 
pressure of a finger or pen against the screen (if that’s available), and MouseWheelDelta. 

You can use as little or as much of this information as you need. Obviously, some of it will not be 
applicable to every pointer device and will therefore have default values. 


A First Dab at Finger Painting 


Perhaps the archetypal multitouch application is one that lets you paint with your fingers on the 
screen. You can write such a program handling just three Pointer events and examining just two 
properties from the event arguments, but \'rr\ afraid the result has a flaw not quite compensated for 
by its simplicity. 

The MainPage.xaml file of FingerPaintl simply provides a name for the standard Grid: 


Project: FingerPaintl I File: MainPage.xaml (excerpt) 

<Page … > 

<Grid Name="contentGri d" 

Background="{Stati cResource ApplicationPageBackgroundThemeBrush}" /> 

</Page> 

The very first thing that the code-behind file does is define a Dictionary with a key of type uint. 

I mentioned earlier that virtually every program that handles Pointer events has a Dictionary of this 
sort. The type of the items you store in the Dictionary is dependent on the application; sometimes an 
application will define a class or structure specifically for this purpose. In a rudimentary finger-painting 
application, each finger touching the screen will be drawing a unique Polyline, so the Dictionary can 
store that Polyline instance: 

Project: FingerPaintl I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 
{ 

Dictionary<uint, Polyline> pointerDictionary = new Di ctionary<ui nt , Polyli ne>() ; 

Random rand = new RandomO; 
byte[] rgb = new byte [3]; 


public MainPage() 

{ 

this .Ini tializeComponent(); 

} 


protected override void OnPointerPressed(Poi nterRoutedEventArgs args) 

{ 

// Get information from event arguments 
uint id = args.Pointer.Pointerld; 

Point point = args.GetCurrentPoi nt(this) .Position; 
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// Create random color 
rand.NextBytes(rgb); 

Color color = Color. FromArgb(255, rgb[0], rgb[l], rgb[2]); 


// Create Polyline 

Polyline polyline = new Polyline 

{ 

Stroke = new SolidColorBrush(color) , 
StrokeThickness = 24, 

}； 

polyline.Points.Add(point); 


// Add to Grid 

contentGrid.Children.Add(poiyline); 


// Add to dictionary 

pointerDictionary.Add(id, polyline); 

base.OnPoi nterPressed(args); 


protected override void OnPointerMoved(Poi nterRoutedEventArgs args) 

{ 

// Get information from event arguments 
uint id = args.Pointer.Pointerld; 

Point point = args.GetCurrentPoint (this) .Position; 

// If ID is in dictionary, add the point to the Polyline 
if (pointerDictionary.ContainsKey(id)) 

pointerDictionary[id].Points.Add(point); 

base.OnPoi nterMoved(args); 

} 


protected override void OnPointerReleased(Poi nterRoutedEventArgs args) 

{ 

// Get information from event arguments 
uint id = args.Pointer.Pointerld; 

// If ID is in dictionary, remove it 
if (pointerDictionary.ContainsKey(id)) 
pointerDictionary.Remove(id); 

base.OnPoi nterReleased(args); 



In the OnPointerPressed override, the program creates a Polyline and gives it a random color. The 
first point is the location of the pointer. The Polyline is added to the Grid and also to the dictionary. 

When subsequent OnPointerMovecJ calls occur, the Poi nter Id property identifies the finger, so the 
particular Polyline associated with that finger can be accessed from the dictionary and the new Point 
value can be added to the Polyline. Because it's the same instance as the Polyline in the Grid, the 
on-screen object will seem to grow in length as the finger moves. 

The OnPointerReleased processing simply removes the entry from the dictionary. That particular 
Polyline is completed. 
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When you run the program, of course the first thing you’ll want to do is sweep your whole hand 
across the screen like the glaciers that created the Finger Lakes in upstate New York. 



Each finger paints its own polyline as a single series of connected points of a particular color, and 
you’ll discover that you can use the mouse and pen as well. 


I mentioned that this code has a flaw. The On Pointer Mo ved and OnPointerReleased overrides are 
very careful to check that the particular ID exists as a key in the dictionary before using it to access 
the dictionary. This is very important for mouse and pen processing because these devices generate 
PointerMovecJ events prior to OnPointerPressecJ. 

But try this: Put the program in a snap mode, and with your finger, draw a line that goes outside 
the page and then back in. 
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Look at that straight line down the left side. That line is drawn when the finger reenters the page, 
and it indicates that the program doesn’t get PointerMoved events during the time the finger strays 
outside. Try it with the mouse. Same thing. 

Now try this: Using a finger, draw a line from the inside of the page to the outside and lift your 
finger. Now use your finger to draw inside the page again. This seems to work OK. 

Now try it with the mouse. Press the mouse button over the FingerPaintl page, move the mouse 
to outside the page, and release the mouse button. Now move the mouse to the FingerPaintl page 
again. The program continues to draw the line even with the mouse button released! This is obviously 
wrong (but I’m sure you’ve seen programs that get "confused" like this). Now press the mouse button, 
and you’ll generate an exception when the OnPointerPressed method attempts to add an entry to the 
dictionary using a key that already exists in the dictionary. Unlike touch or the pen, all mouse events 
have the same ID. 

Let’s fix these problems. 

Capturing the Pointer 

To allow me (and you) to get a better sense of the sequence of Pointer events, I wrote a pro¬ 
gram called PointerLog that logs all the Pointer events on the screen. The core of the program is a 
User Control called LoggerControl. The Grid in the LoggerControl.xaml file has been given a name but 
is otherwise initially empty: 


Project: PointerLog I File: LoggerControl.xaml (excerpt) 

<UserControl … > 

<Grid Name="contentGri d" Background="Transparent" /> 

</UserControl > 

The code-behind file has overrides of all eight Pointer methods, all of which call a method named 
Log with the event name and event arguments. Like all Pointer programs, a Dictionary is defined, but 
the values in this one are not simple objects. Instead, I defined a nested class named Pointerlnfo right 
at the top of the LoggerControl class for storing per-finger information in this dictionary. 


Project: PointerLog I File: LoggerControl.xaml.es (excerpt) 

public sealed partial class LoggerControl : UserControl 
{ 

class Pointerlnfo 
{ 

public StackPanel stackPanel; 
public string repeatEvent; 
public TextBlock repeatTextBlock; 


Dictionary<uint, PointerInfo> pointerDictionary = new Dictionary<uint, PointerInfo>() ; 


622 PART: Specialties 



public LoggerControl() 


this .InitializeComponent(); 

} 

public bool CaptureOnPress { set ; get; } 

protected override void OnPointerEntered(Poi nterRoutedEventArgs args) 

{ 

LogC'Entered" , args); 
base. OnPointerEntered(args); 

} 

protected override void OnPointerPressed(Poi nterRoutedEventArgs args) 

{ 

if (this .CaptureOnPress) 

CapturePointer(args.Pointer); 

LogC'Pressed" , args); 
base. OnPointerPressed(args); 

} 

protected override void OnPointerMoved(Poi nterRoutedEventArgs args) 

{ 

LogC'Moved" , args); 
base. OnPointerMoved(args); 

} 

protected override void OnPointerReleased(Poi nterRoutedEventArgs args) 

{ 

LogC'Released" , args); 
base. OnPointerReleased(args); 

} 

protected override void OnPointerExited(Poi nterRoutedEventArgs args) 

{ 

LogC'Exited" , args); 
base. OnPointerExi ted(args); 

} 

protected override void OnPointerCaptureLost(Poi nterRoutedEventArgs args) 

{ 

LogC'CaptureLost" , args); 
base. OnPointerCaptureLost(args); 

} 

protected override void OnPointerCanceled(Poi nterRoutedEventArgs args) 

{ 

LogC'Cancel ed" , args); 
base. OnPointerCancel ed(args); 

} 

protected override void OnPointerWheelChanged(Poi nterRoutedEventArgs args) 

{ 

LogC'WheelChanged" , args); 
base. OnPointerWheelChanged(args); 


} 
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void LogCstri ng eventName, PointerRoutedEventArgs args) 

{ 

uint id = args.Pointer.Pointerld; 

Pointerlnfo pointerlnfo; 

if (pointerDictionary.Containsl<ey(id)) 

{ 

pointerlnfo = pointerDictionary[id]; 

} 

else 

{ 

// New ID, so new StackPanel and header 
TextBlock header = new TextBlock 
{ 

Text = args. Poi nter. Poi nterld + "-■• + args. Poi nter. Poi nterDevi ceType, 
FontWeight = FontWeights.Bold 

}； 

StackPanel StackPanel = new StackPanel (); 

StackPanel.Chi Idren.Add(header); 

// New Pointerlnfo for dictionary 
pointerlnfo = new Pointerlnfo 
{ 

StackPanel = StackPanel 

}； 

pointerDictionary.Add(id, pointerlnfo); 

// New column in the Grid for the StackPanel 
ColumnDefinition coldef = new ColumnDefinition 
{ 

Width = new Gri dLength(l, GridUnitType .Star) 

}； 

contentGrid.ColumnDefinitions.Add(coldef); 

Gri d.SetColumn(StackPanel, contentGrid.ColumnDefinitions.Count - 1); 
contentGrid.Children.Add(StackPanel); 

} 

// Don't repeat PointerMoved and PointerWheelChanged events 
TextBlock txtblk = null; 

if (eventName == pointerlnfo.repeatEvent) 

{ 

txtblk = pointerlnfo.repeatTextBlock; 

} 

else 

{ 

txtblk = new TextBl ock() ; 

pointerlnfo.StackPanel.Children.Add(txtblk); 

} 

txtblk.Text = eventName + "" ; 

if (eventName == "WheelChanged") 

{ 

txtblk.Text += args.GetCurrentPoi nt(this) •Properties.MouseWheelDelta; 
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} 

else 

{ 

txtblk.Text += args.GetCurrentPoi nt(thi s). Position; 

} 

txtblk.Text += args.Pointer.IsInContact ? " C" : 
txtblk.Text += args.Pointer.IsInRange ? " R" : 

if (eventName == "Moved" | | eventName == "WheelChanged") 

{ 

pointerlnfo.repeatEvent = eventName; 
pointerlnfo.repeatTextBlock = txtblk; 

} 

else 

{ 

pointerlnfo.repeatEvent = null ; 
pointerlnfo.repeatTextBlock = null; 

} 


public void Clear() 

{ 

contentGrid.ColumnDefinitions.Cl ear(); 
contentGrid.Children.ClearO ; 
pointerDictionary.Clear(); 



The Log method seems rather complicated, but every time it encounters a new Poi nter Id value in 
the event arguments, it adds a new column to the Grid, puts a TextBlock at the top indicating the ID 
and device type, and adds an entry to the dictionary. All subsequent events with that ID go in that 
column, except that consecutive Poi nter Moved and PointerWheelChongecJ events don’t get extra 
entries. There’s no scrolling facility and eventually there will be too many columns, but a public Clear 
method restores everything to a pristine condition. 

The LoggerControl only gets Pointer events for that control. To ease the examination of what 
happens when fingers move between controls, I made LoggerControl part of a larger page with the 
program name at the top and three buttons at the bottom: 


Project: PointerLog I File: MainPage.xaml (excerpt) 

<Grid Background^' {StaticResource ApplicationPageBackgroundThemeBrush}"> 
<Grid.RowDefinitions> 

〈RowDefinition Hei ght="Auto" /> 

〈RowDefinition Height="*" /> 

<RowDefinition Height="Auto" /> 

</Grid.RowDefinitions> 


<TextBlock Text="Poi nter Event Log" 

Grid.Row="0" 

Styl e="{StaticResource HeaderTextStyl e} 
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HorizontalAli gnment="Center" 

Margin="12" /> 

<local : LoggerControl x : Name="logger" 

Grid.Row="l" 

FontSi ze="{StaticResource ControlContentThemeFontSi ze}" /> 


<Grid Grid. Row="2"> 

<Grid.ColumnDefinitions> 

<Co1umnDefinition Width="*" /> 

<Co1umnDefinition Width="*" /> 

<Co1umnDefinition Width="*" /> 

</Grid.ColumnDefinitions> 

<Button Content="Cl ear" 

Grid.Col umn="0" 

HorizontalAli gnment="Center" 

Cli ck="OnCl earButtonClick" /> 

<ToggleButton Name=" captureButton" 

Content="Capture on Press" 

Grid.Col umn="l" 

HorizontalAli gnment="Center" 

Checked="OnCaptureToggl eButtonChecked" 
Unchecked="OnCaptureToggl eButtonChecked" /> 

<Button Content="Rel ease Captures in 5 seconds" 

Grid.Column="2" 

IsEnabl ed="{Binding El ementName=captureButton , Path=IsChecked} 
HorizontalAli gnment="Center" 

Cli ck="OnRel easeCapturesButtonClick" /> 

</Grid> 

</Crid> 

Notice the final Button is enabled only when the ToggleButton is toggled on. 

The code-behind file just handles the buttons (which I’ll discuss shortly): 


Project: PointerLog I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

DispatcherTimer timer; 

public MainPageC) 

{ 

this .InitializeComponent(); 

timer = new DispatcherTimer { Interval = TimeSpan. FromSeconds(5) }; 
timer.Tick += OnTimerTick; 

} 

void OnClearButtonCli ck(object sender, RoutedEventArgs args) 

{ 

logger.Clear(); 

} 

void OnCaptureToggleButtonChecked (object sender, RoutedEventArgs args) 
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} 


ToggleButton toggle = sender as ToggleButton ; 

logger.CaptureOnPress = toggle.IsChecked.Value; 


void OnReleaseCapturesButtonCIick (object sender, RoutedEventArgs args) 

{ 

timer.Start(); 

} 

void OnTimerTi ck(object sender, object args) 

{ 

logger.ReleasePointerCapturesC); 
timer.Stop(); 



You can see from the screen that each new finger press gets a unique ID and generates only five 
events. Each new series of pen events also gets its own ID (using the same numbering sequence as 
touch) with a few more events. The mouse always has an ID of 1: 


59 - Touch 

Entered 421.5189,156.4971 C R 
Pressed 421.5189,156.4971 C R 
Moved 869.1601,365.4058 C R 
Released 869.1601,365.4058 
Exited 869.1601,365.4058 


60 - Touch 

Entered 516.5607,192.316 C R 
Pressed 516.5607,192.316 C R 
Moved 1063.425,508.0494 C R 
Released 1063.425,508.0494 
Exited 1063.425,508.0494 


Pointer Event Log 


61 • Touch 

Entered 415.8918,353.9226 C R 
Pressed 415.8918,353.9226 C R 
Moved 1066.833,351.5523 C R 
Released 1066.833,351.5523 
Exited 1066.833,351.5523 


Clear 


Capture on Press 


62-Pen 

Entered 502.4606,358.9297 R 
Moved 576.4722,371.0058 R 
Pressed 577.9598,370.7939 C R 
Moved 1075.214,409.4588 C R 
Released 1075.214,409.4588 R 
Moved 1095.191,385.6243 
Exited 1095.191,385.6243 


1 - Mouse 

Entered 0.9845184,272 R 
Moved 435.9708,418.9858 R 
Pressed 435.9708,418.9858 C R 
Moved 676.9915,420.989 C R 
Released 676.9915,420.989 R 
Moved 0.9845184,275.9685 R 
Exited 0.9845184,275.9685 R 


Release Captures In 5 seconds 


The letters C and R indicate true values of the I sin Contact and Isln Range properties of the Pointer 
object. As you can see, for the pen and mouse you can use the IsInRonge property to distinguish 
between PointerMovecJ events that occur when the pen is touching the screen or when the mouse 
button is pressed. 

By default, an element gets Pointer input only when the pointer is within the boundaries of 
the element. This can sometimes result in a loss of information. To demonstrate this, I deliberately 
designed the program so that LoggerControl does not extend to the full height of the screen. Above 
it is an area for the program title, and below is the button area. These areas are the domain of 
Main Page. This configuration allows you to experiment with input that moves from one element to 
another. 
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For example, touch the PointerLog screen somewhere in the middle, move your finger around, 
and then move the finger to the top title area or the bottom button area. Lift it off the screen. The 
program does not receive that PointerReleasecJ event, and it has no idea that the pointer has been 
released. It will never get another event with that particular ID number, but it’s living in a state of 
ignorance. The entry in the dictionary is never removed. 


Similarly, touch the screen in the top or bottom area and move your finger to the central area. The 
program registers PointerEntered and PointerMoved events but not a PointerPressed event. 

Often while tracking a particular pointer, you want to continue getting input even if it drifts 
outside the element. Not getting that pointer input accounts for the flaws in the FingerPaintl 
program. 

You can get what you want with a process called "capturing the pointer," which you do with 
a call to the CopturePointer method defined by UlElement. The method has an argument of 
type Pointer and returns a bool indicating if the pointer capture has been successful. When will 
it not be successful? If you call CopturePointer during an event prior to PointerPressed or during 
PointerReleosed or later. 


For this reason — and for the sake of program politeness — it really only makes sense to call 
CopturePointer during a PointerPressed event. By pressing a finger (or pen or mouse button) on a 
particular element, the user is generally indicating a desire to interact with that element even if the 
finger sometimes drifts outside the element. 


If you toggle on the "Capture on Press” button at the bottom of the PointerLog screen, the 
program calls 

CapturePointer(args.Pointer); 
during the On Poin ter Pressed override. 

Now if you press in the central area of the PointerLog program, move your finger to the 
top or bottom, and then release, the program logs the PointerReleosed event as well as a final 
PointerCaptureLost event following PointerExited. 

A program can get a list of all the captured pointers with a call to PointerCoptures and 
release a particular capture with a ReleasePoin ter Cop ture call or release all pointer captures with 
ReleosePointerCoptures. 


In a real-life application it is tempting to simply ignore the PointerCaptureLost event, but it’s not a 
good idea. If Windows needs to communicate something urgent to the user, it’s possible that pointer 
capture will be snatched from a program involuntarily. I have not actually seen this happen under 
Windows 8, but historically it occurs upon the display of a system modal dialog box — a dialog box 
that considers itself so important that it gets all user input until it’s dismissed. 

To demonstrate what happens in such a case, I’ve defined the third button to set a DispotcherTimer 
for five seconds and then conclude by calling ReleosePointerCoptures for the LoggerControl. When 
that happens, a pointer that has been captured fires a PointerCaptureLost event. The element 
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continues to receive other Pointer events if the pointer is still over the element but not if it drifts 
outside the element. 

What an application should do when it receives an unexpected PointerCaptureLost depends 
on the application. For a finger-paint program you might want to move PointerReleased logic into 
PointerCaptureLost, for example, and treat both expected and unexpected losses of capture as the 
same. 

Or, it might make sense to entirely discard that particular drawing event. 

In fact, you might want to build this feature into your program. Suppose you decide that the user 
should be able to press the Esc key to jettison a drawing event that’s in progress. You could then 
implement Esc-key processing with a simple call to ReleosePointerCaptures. 

The FingerPaint2 program does precisely that. The XAML file is the same as FingerPaintl, and so is 
the code-behind file with the following exceptions: 


Project: FingerPaint2 I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 


public MainPage() 

{ 

this .InitializeComponent(); 
this .IsTabStop = true ; 


protected override void OnPointerPressed(Poi nterRoutedEventArgs args) 
{ 

// Capture the Pointer 
CapturePointer(args.Poi nter); 

// Set input focus 

Focus (FocusState .Programmatic); 

base. OnPointerPressed(args); 

} 


protected override void OnPointerCaptureLost(Poi nterRoutedEventArgs args) 
{ 

// Get information from event arguments 
uint id = args.Pointer.Pointerld; 

// If ID is in dictionary, abandon the drawing operati on 
if (pointerDictionary.ContainsKey(id)) 

{ 

contentGrid.Children.Remove(pointerDictionary[i d]); 
pointerDictionary.Remove(id); 

} 

base. OnPointerCaptureLost(args); 

} 
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protected override void OnKeyDown (KeyRoutedEventArgs args) 

{ 

if (args.Key == Virtual Key. Escape) 

ReleasePointerCaptures(); 

base. OnKeyDown(args); 

} 

} 

In the constructor, the IsTobStop property must be set to true for the element to receive keyboard 
input. Only one element can receive keyboard input at any time. This is called the element with key¬ 
board "focus," and some controls indicate they have keyboard focus with a special appearance, such 
as a dotted line. Often an element can give itself keyboard focus by calling the Focus method when 
the element is tapped or (in this case) during the OnPointerPressed event. That override concludes its 
processing by calling the Focus method as well as Capture Pointer. 

The OnPointerCaptureLost method removes the Polyline in progress from the Grid and removes 
the ID from the dictionary. However, the PointerCoptureLost event can occur normally after a finger 
has been released from the screen, so this ID will still be in the dictionary only if the page didn’t get a 
call to OnPointerReleosed. 

The OnKeyDown method gets keystrokes and calls ReleasePointerCaptures for Esc. This call has no 
effect if no pointers are captured. 

Try the problematic actions identified with the FingerPaintl, and you’ll find that they’re gone in 
this version. Moreover, now you can be drawing on the screen and press Esc, and what you're cur¬ 
rently drawing will disappear and the finger will have no further effect until it’s released and pressed 
again. (Let’s hope that’s what you want.) 

Editing with a Popup Menu 


Let’s add an editing feature to this program. If you click an existing Polyline with the right mouse 
button — or you do something equivalent with a finger or pen — a little menu pops up with the op¬ 
tions "Change color" and "Delete .〃 

In the previous two FingerPaint programs, the Polyline was created, initialized, and added to the 
content Grid and touch dictionary like so: 


// Create Polyline 
Polyline polyline = new Polyline 
{ 

Stroke = new SolidColorBrush(color) , 
StrokeThickness = 24, 

}； 

polyline.Points.Add(point); 

// Add to Grid 

contentGrid.Children.Add(polyline); 

// Add to dictionary 

pointerDictionary.Add(id, polyline); 
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For FingerPaint3 let’s add some additional code that sets two event handlers on this Polyline. The 
goal here is to use the handler for the RightTapped event of the Polyline to display a popup menu: 


Project: FingerPaint3 | File: MainPage.xaml.es (excerpt) 

protected override void OnPointerPressed(Poi nterRoutedEventArgs args) 
{ 

// Create Polyline 

Polyline polyline = new Polyline 

{ 

Stroke = new SolidColorBrush(color) , 

StrokeThickness = 24, 

}； 

polyline.PointerPressed += OnPoiylinePointerPressed; 
polyline.RightTapped += OnPoiylineRightTapped; 
polyline.Points.Add(point); 

} 


Although we’re interested only in the RightTapped event for the Polyline, I’ve also set a handler for 
the PointerPressed event. That handler is not very interesting, but it’s very important: 


Project: FingerPaint3 I File: MainPage.xaml.es (excerpt) 

void OnPolylinePoi nterPressed(object sender, PointerRoutedEventArgs args) 
{ 

args.Handled = true; 

} 


You'll definitely want to try this program without this particular handler, and here's why: When 
a PointerPressed event is fired, that event is associated with the topmost element that is enabled 
for user input. If you’re clicking or right-clicking a Polyline rather than the surface of Mo in Page, the 
PointerPressed event is fired for that Polyline. 

However, PointerPressed is a routed event, and you’ll recall from Chapter 3, "Basic Event Handling,” 
that routed events travel up the visual tree, which means that if the Polyline isn’t interested in this 
event, it will go to MainPage, which will assume that you want to begin drawing a new figure. To 
prevent that from happening in this program, the Polyline handles the PointerPressed event by set¬ 
ting the Handled property on the event arguments to true. This prevents the event from reaching 
Main Page. 

The popup menu logic occurs in the RightTapped event: 


Project: FingerPaint3 I File: MainPage.xaml.es (excerpt) 

async void OnPoi yl "i neRi ghtTapped (object sender, Ri ghtTappedRoutedEventArgs args) 

{ 

Polyline polyline = sender as Polyline; 

PopupMenu popupMenu = new PopupMenuO; 

popupMenu.Commands .Add(new UICommand("Change color" , OnMenuChangeColor, polyline)); 
popupMenu.Commands.Add (new UICommand("Del ete " ， OnMenuDelete, polyline)); 
await popupMenu.ShowAsync(args.GetPositi on(this)) ; 
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As I demonstrated in Chapter 8, "App Bars and Popups,” it’s fairly easy to use PopupMenu. After 
creating the object, you can add up to six items to the menu. Each item consists of a text label, a 
callback, and an optional object to help the callback identify the event. The ShowAsync method 
displays the menu at a particular location. 

The handlers can obtain that last argument passed to the UlCommoncJ constructor by casting the 
Id property of the callback method's lUICommond argument: 

Project: FingerPaint3 I File: MainPage.xaml.es (excerpt) 

void OnMenuChangeColorCIUICommand command) 

{ 

Polyline polyline = command.Id as Polyline; 
rand.NextBytes(rgb); 

Color color = Color. FromArgb(255, rgb[0], rgb[l], rgb[2]); 

(polyline.Stroke as SolidColorB rush) .Color = color; 

} 

void OnMenuDel ete(IUICommand command) 

{ 

Polyline polyline = command.Id as Polyline; 
contentGrid.Children.Remove(polyline); 

} 

I’m sure you already know how to use the mouse to right-click a Polyline. With touch, you’ll need 
to hold your finger steady on a Polyline for a moment, and then release. You’ll see a square form 
when you’ve held long enough. Similarly with a pen, hold it until you see a circle form, and then 
release. The menu appears: 



The square and circle you see when you hold your finger or the pen to the screen are actually 
associated with the Holding event. If you set the IsHoldingEnobled property on the Polyline to false, 
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they won’t appear and the user might be a little uncertain how long to press. The RightTapped event 
isn’t fired until the user lifts the finger or pen from the screen. 

The OnMenuDelete method in FingerPaintB actually has a subtle bug. If one finger is drawing a 
line while another finger invokes the menu for that line, OnMenuDelete removes the Polyline from 
the screen but not the dictionary entry with that Polyline. Nothing bad will happen, but the diction¬ 
ary might accumulate some abandoned entries. Logic to fix this would have to search through the 
dictionary for the deleted Polyline and then remove the key for that entry. 

As I demonstrated with routed events in Chapter B, whenever you’re dealing with events 
generated by different elements, you can structure your event handling in various ways. For 
example, an On Poin ter Pressed override in Main Page can incorporate the logic that I put in 
OnPolylinePointerPressed, and you can perform all the RightTapped handling in an OnRightTapped 
override. All you need do is check the OriginalSource property on the event arguments to determine 
whether the input is coming from the Polyline or Main Page. 

The program now has a little drawback. You can’t draw a new line if you want to begin that line on 
a point occupied by an existing line. Any Pointer Pressed event received by the Polyline is flagged as 
Handled and essentially discarded. 

What if you wanted to give the user both options? If the user presses an existing Polyline and starts 
moving, a new figure is started. If the user presses and holds, that’s a menu. 


Probably the easiest approach is abandoning the use of the RightTapped event and handling 
everything through the Pointer logic. When OnPointerPressed occurs on an existing Polyline, 
set a DispatcherTimer for one second, but cancel that timer (and start a drawing operation) if 
OnPointerMoved occurs, indicating that the finger has moved a distance greater than some preset 
criteria. If the timer fires, display the menu. 


Pressure Sensitivity 


The lines drawn by the various FingerPaint programs are of a uniform stroke thickness — 24 pixels to 
be precise — but some touch devices can differentiate heavier touches from lighter touches, and a 
really good FingerPaint program would respond by varying the stroke thickness. 

There are two properties that might influence line thickness in a finger-painting program, and 
both are defined by the PointerPointProperties object returned from the Properties property of 
the PointerPoint class (which in turn is obtained by a call to the GetCurrentPoint method of the 
PointerRoutedEventArgs event arguments). 


The first property is ContoctRect, a Red value that is intended to report the rectangular bounding 
box of the contact area of a finger (or pen point) on the screen. This property will probably only apply 
to rather esoteric touch devices. On the tablet I’ve been using for most of this book, this Rect always 
has a Width and Height of zero regardless of the pointer device. On the first versions of the Microsoft 
Surface tablet, the Width and Height values are low-value integers, such as 1, 2, and 3, that don’t 
seem as if they can be used for much. (But I might be wrong.) 
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The second property is Pressure, which is a float value that can take on values between 0 and 1. 

On the tablet I’ve been using for most of this book, this Pressure value is the default value of 0.5 for 
fingers and the mouse, but it is variable for the pen, and so I had the opportunity to try it out. (On the 
first versions of the Microsoft Surface tablet, the Pressure value is always 0.5.) 

For purposes of simplicity, the FingerPaint4 program does not include Esc-key processing or 
the editing feature, but it does implement pointer capturing. The big difference is that the Polyline 
approach to drawing must be abandoned because a Polyline has only a single StrokeThickness 
property. In this new program each stroke must instead be composed of very short individual lines, 
each a unique StrokeThickness that is calculated from the Pressure value, but all the same color. This 
implies that the dictionary needs to contain values of type Color (or better yet, a Brush) and the 
previous Point. This is now two items, so let's define a custom structure for that purpose that I called 
Pointer! nfo: 

Project: FingerPaint4 | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 
{ 

struct Pointerlnfo 
{ 

public Brush Brush; 
public Point PreviousPoint; 

} 

Dicti onary<ui nt , Pointerlnfo pointerDictionary = new Di ctionarycui nt ， PointerInfo>() ; 

Random rand = new RandomO; 
byte[] rgb = new byte [3]; 

public MainPage() 

{ 

this .InitializeComponent(); 

} 

protected override void OnPointerPressed(Poi nterRoutedEventArgs args) 

{ 

// Get information from event arguments 
uint id = args.Pointer.Poi nterld; 

Point point = args.GetCurrentPoint (thi s) .Position; 

// Create random color 
rand.NextBytes(rgb); 

Color color = Color. FromArgb(255, rgb[0] , rgb[l], rgb[2]); 

// Create Pointerlnfo 

Pointerlnfo pointerlnfo = new Pointerlnfo 
{ 

PreviousPoint = point, 

Brush = new Soli dColorBrush(color) 

}； 
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// Add to dictionary 

pointerDictionary.Add(id, pointerlnfo); 

// Capture the Pointer 
CapturePointer(args.Poi nter); 

base .OnPointerPressed(args); 

} 


protected override void OnPointerReleased(Poi nterRoutedEventArgs args) 

{ 

// Get information from event arguments 
uint id = args.Pointer.Pointerld; 

// If ID is in dictionary, remove it 
if (pointerDictionary.ContainsKey(id)) 
pointerDictionary.Remove(id); 

base. OnPointerReleased(args); 

} 


protected override void OnPointerCaptureLost(Poi nterRoutedEventArgs args) 

{ 

// Get information from event arguments 
uint id = args.Poi nter .Poi nterld; 

// If ID is still in dictionary, remove it 
if (pointerDictionary.ContainsKey(id)) 
pointerDictionary■Remove(id); 

base. OnPointerCaptureLost(args); 

} 

} 


The earlier PointerPressed handlers created a Polyline, gave it an initial point, and added it to the 
Grid and Dictionary. In this program, only a Poi nterlnfo value is created and added to the dictionary. 
Much more work occurs in the PointerMoved handler, particularly because IVe also decided to use 
GetlntermediotePoints rather than GetCurrentPoint, resulting (at least theoretically) in smoother 
strokes on the Microsoft Surface. But one oddity I discovered is that these points are in the collection 
in reverse order! 
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This code loops through the points. For each new point and the previous point, a Line element is 
constructed and added to the Grid. The last point then replaces the previous point in the Pointerlnfo 
value: 


Project: FingerPaint4 | File: MainPage.xaml.es (excerpt) 

protected override void OnPointerMoved(Poi nterRoutedEventArgs args) 

{ 

// Get ID from event arguments 
uint id = args.Pointer.Pointerld; 

// If ID is in dictionary, start a loop 
if (pointerDictionary.ContainsKey(id)) 

{ 

Pointerlnfo pointerlnfo = pointerDictionary[id]; 

IList<PointerPoi nt> pointerpoints = args.GetlntermediatePoi nts(this) ; 

for (int i = pointerpoints.Count - 1; i >= 0; i--) 

{ 

PointerPoint pointerPoint = pointerpoints[i]; 

// For each point, create a new Line element and add to Grid 

Point point = pointerPoint.Position; 

float pressure = pointerPoint.Properties.Pressure; 

Line line = new Line 

{ 

XI = pointerlnfo.PreviousPoint.X, 

Y1 = pointerlnfo.PreviousPoint.Y, 

X2 = point.X, 

Y2 = point.Y, 

Stroke = pointerlnfo.Brush, 

StrokeThickness = pressure * 24, 

StrokeStartLineCap = PenLineCap. Round, 

StrokeEndLineCap = PenLineCap. Round 

}； 

contentGrid.Children.Add(line); 

// Update Pointerlnfo 

pointerlnfo.PreviousPoint = point; 

} 

// Store Pointerlnfo back in dictionary 
pointerDictionary[id] = pointerlnfo; 

} 

base .OnPointerMoved(args); 

} 


Notice that the StrokeThickness is set to 24 times the Pressure value. This results in a maximum 
stroke thickness of 24 and a stroke thickness of 12 for non-pressure-sensitive devices. Notice also that 
the StrokeStartLineCop and StrokeEndLineCop properties are set to Round. Try commenting out these 
property settings and see what happens when a stroke has sharp turns: Little gaps appear because 
two short lines are at an angle to each other. The line caps cover those gaps. 
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Here’s a little, umm, artwork I did entirely with the pen: 



Notice the graceful subtlety of the strokes when rendered with a pressure-sensitive input device. 

It is my experience that PointerMoved events can be fired as quickly as 100 times per second, which 
is faster than the frame rate of the video display but not quite fast enough for extremely energetic 
fingers. 


Smoothing the Tapers 


Have you ever noticed that solving one problem often reveals another problem? To my mind, 
allowing for pressure sensitivity is an important feature in a finger-painting program. Yet, if you draw 
something very fast with a pressure-sensitive pen in FingerPaint4, you might notice that lines don’t 
seem to taper correctly. Instead, they increase or decrease in size with discrete jumps: 



Well, of course. Each of those pieces in the lower-right portion of that squiggle is a separate Line 
element with its own StrokeThickness. I drew the squiggle with such speed that the pressure varied 
considerably between each event, which made the thickness jump in visible discontinuities. 
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If you consider that a particular Line element can have only one constant StrokeThickness, it might 
seem difficult to fix this problem. But the solution is actually quite easy (at least conceptually): Rather 
than drawing a Line for each event, draw a filled Path consisting of two arcs with different radii 
connected by two lines. 

To make this job a little easier, you’ll want to make use of a Vector structure, which every modern 
operating system should include but the Windows Runtime does not Here’s a structure I call Vector2 
(the "2" is for two dimensions) that is part of a larger library that youll encounter in Chapter 14. 
Hence, the long namespace name: 


Project: FingerPaint5 I File: Vector2.cs 

using System; 

using Windows■Foundation; 

using Windows.UI.Xaml.Media; 

namespace Petzold.Windows8.VectorDrawing 

{ 

public struct Vector2 

{ 

// Constructors 

public Vector2 (double x, double y) 
: this() 

{ 

X = x; 

Y = y; 

} 

public Vector2 (Poi nt p) 

: this() 

{ 

X = p.X; 

Y = P-Y ； 

} 


public Vector2 (double angle) 

: this() 

{ 

X = Math. Cos (Math. PI * angle / 180); 
Y = Math. Sin (Math. PI * angle / 180); 

} 

// Properties 

public double X { private set; get; } 
public double Y { private set; get; } 


public double LengthSquared 

{ 

get { return X * X + Y * Y; } 

} 

public double Length 

{ 

get { return Math. Sqrt(LengthSquared); } 

} 

public Vector2 Normalized 


638 PART Specialties 


{ 


get 


double length = this .Length; 


if (length != 0) 

{ 

return new Vector2(thi s .X / length, 

thi s.Y / length); 

} 

return new Vector2() ; 

} 

} 

// Methods 

public Vector2 Rotate(doubl e angle) 

{ 

RotateTransform xform = new RotateTransform { Angle = angle }; 

Point pt = xform.TransformPoi nt(new Poi nt(X, Y)); 
return new Vector2(pt .X, pt.Y); 

} 

// Static methods 

public static double AngleBetween(Vector2 vl, Vector2 v2) 

{ 

return 180 * (Math .Atan2(v2.Y, v2_X) - Math .Atan2(vl.Y, vl.X)) / Math. PI; 

} 

// Operators 

public static Vector2 operator +(Vector2 vl, Vector2 v2) 

{ 

return new Vector2(vl.X + v2.X, vl.Y + v2.Y); 

} 

public static Point operator +(Vector2 v, Point p) 

{ 

return new Point(v.X + p.X, v.Y + p.Y); 

} 

public static Point operator +(Poi nt p, Vector2 v) 

{ 

return new Point(v.X + p.X, v.Y + p.Y); 

} 

public static Vector2 operator -(Vector2 vl, Vector2 v2) 

{ 

return new Vector2(vl.X - v2.X, vl.Y - v2.Y); 

} 

public static Point operator -(Poi nt p, Vector2 v) 

{ 

return new Poi nt(p.X - v.X, p.Y - v.Y); 

} 

public static Vector2 operator *(Vector2 v, double d) 

{ 

return new Vector2(d * v.X, d * v.Y); 

} 
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public static Vector2 operator * (double d, Vector2 v) 


return new Vector2(d * v.X, d * v_Y); 

} 

public static Vector2 operator /(Vector2 v, double d) 
{ 

return new Vector2(v.X / d, v.Y / d); 

} 


public static Vector2 operator -(Vector2 v) 


return new Vector2(-v.X, -v.Y); 

} 

public static explicit operator Point(Vector2 v) 
{ 

return new Poi nt(v.X, v.Y); 

} 


// Overrides 

public override string ToString() 


return String. Format ("({0} {1})", X, Y); 


FingerPaintS saves the previous radius (based on the pressure setting) along with the previous point. 
In this diagram, I’ve represented two consecutive finger locations as circles with independent radii. The 
smaller circle has a center cO and radius rO, and the larger circle has a center cl and radius rl: 



The goal here is to derive a Path that encompasses those two circles and the area between them. 
To do this, we must connect the two circles with lines that are tangent to both circles, and that’s a 
little tricky (mathematically speaking). Let's first connect the centers of the two circles with a line 
labeled d: 
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A Vector2 value lets us obtain the length of that line and a normalized vector representing its 
direction: 

Vector2 vCenters = new Vector2(c0) - new Vector2 (cl); 
double d = vCenters.Length; 
vCenters = vCenters.Normalized; 

Now let’s define another length named e based on d and the radii of the two circles. The point F is 
e distance from cO and in the same direction as the vector between the two centers: 

double e = d * rO / (rl - rO); 

Point F = cO + e * vCenters; 

Here it is: 



I called that point F because I think of it as a "focal point/' I contend that there exist lines from F 
that are tangent to both circles, meaning a right angle is formed with that line and a radius line: 



I know this because of the way that e was defined. The ratio of e to rO is the same as the ratio of d 
plus e to rl. That angle a (toward the right of the figure) is simply calculated like so: 

double alpha = 180 * Math .Asin(r0 / e) / Math. PI; 

If the argument to the Moth.Asin method is greater than 1, the method returns NaN (not a number). 
This can happen only if rO plus d is less than rl — that is, if the smaller circle is entirely enclosed in the 
larger circle. That makes this problem easy to anticipate. 


The lengths of those triangle legs from F to the tangent points can be calculated with the 
Pythagorean theorem: 

double legO = Math.Sqrt(e * e - rO * rO); 

double legl = Math.Sqrt((e + d) * (e + d) - rl * rl); 


The Vector2 structure has a convenient Rotate method that allows us to rotate the vCenters vector 
by a and -a degrees: 

Vector2 vRight = -vCenters.Rotate(alpha); 

Vector2 vLeft = -vCenters.Rotate(-alpha); 
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The "right” and "left” parts of the variable names are from the perspective of F. In the diagram, the 
vRight vector corresponds to the tangent line on the top of the circles, and vLeft to the bottom. The 
vectors and the lengths allow us to calculate the actual tangent points: 

Point tOR = F + legO * vRight; 

Point tOL = F + legO * vLeft; 

Point tlR = F + legl * vRight; 

Point tlL = F + legl * vLeft; 

These points can then be used to construct a PathGeometry that consists of two ArcSegment 
objects and two LineSegment objects, shown here as a heavy outline: 



Notice that the ArcSegment on the smaller circle is always less than 180 degrees and the 
ArcSegment on the larger circle is always greater than 180 degrees. These characteristics affect the 
IsLorgeArc property of ArcSegment. Also keep in mind that one of the two LineSegment objects can 
be created implicitly by specifying that the figure should be closed. 

Here’s the actual algorithm defined in FingerPaint5. Notice that it also must implement the 
relatively simpler case where the two radii are the same, or where one circle is enclosed in the other: 


Project: FingerPaint5 I File: MainPage.xaml.es (excerpt) 

Geometry CreateTaperedLineGeometry(Poi nt cO, double r0, Point cl, double rl) 
{ 

// Swap the centers and radii so that cO is 
// the center of the smaller circle, 

if (rl < r0) 

{ 

Point point = cO; 
cO = cl; 
cl = point; 

double radius = r0; 
r0 = rl; 
rl = radius; 

} 

// Get vector from cl to cO 

Vector2 vCenters = new Vector2(c0) - new Vector2(cl) ; 


// Get "length and normalized version 
double d = vCenters.Length; 
vCenters = vCenters.Normalized; 

// Determine if one circle is enclosed in the other 
bool enclosed = r0 + d < rl; 
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// Define tangent points derived in both algorithms 
Point tOR = new Poi nt() ; 

Point tOL = new Poi nt() ; 

Point tlR = new Poi nt() ; 

Point tlL = new Poi nt() ; 

// Case for two circles of same size 
if (rO == rl I I enclosed) 

{ 

// Rotate centers vector 90 degrees 

Vector2 vLeft = new Vector2(-vCenters.Y, vCenters.X); 

// Rotate -90 degrees 
Vector2 vRight = -vLeft; 


// Find tangent points 
tOR = cO + rO * vRight; 
tOL = cO + rO * vLeft; 
tlR = cl + rl * vRight; 
tlL = cl + rl * vLeft; 

} 

//A bit more difficult for two circles of unequal size 
el se 
{ 

// Create focal point F extending from cO 
double e = d * rO / (rl - 「 0); 

Point F = cO + e * vCenters; 


// Find angle and length of right-triangle legs 
double alpha = 180 * Math .Asin(rO / e) / Math .PI; 
double legO = Math.Sqrt(e * e - rO * rO); 
double legl = Math.Sqrt((e + d) * (e + d) - rl * rl); 


// Vectors of tangent "lines 

Vector2 vRight = -vCenters.Rotate(alpha); 

Vector2 vLeft = -vCenters.Rotate(-alpha); 


// Find tangent points 
tOR = F + legO * vRight; 
tOL = F + legO * vLeft; 
tlR = F + legl * vRight; 
tlL = F + legl * vLeft; 


// Create PathGeometry with implied closing line 
PathGeometry pathGeometry = new PathGeometryO ; 
PathFigure pathFigure = new PathFigure 
{ 一 
StartPoint = tOR, 

IsClosed = true , 

IsFilied = true 

}； 

pathGeometry.Figures.Add(pathFi gure); 


// Arc around smaller circle 
ArcSegment arcOSegment = new ArcSegment 


Point = tOL, 

Size = new Si ze(rO, rO), 

SweepDirecti on = SweepDirecti on .Clockwise, 
IsLargeArc = false 

}； 

pathFigure.Segments.Add(arcOSegment); 

// Line connecting smaller circle to larger circle 
LineSegment 1ineSegment = new LineSegment 
{ 

Point = tlL 

}； 

pathFigure■Segments.Add(lineSegment); 


// Arc around larger circle 
ArcSegment arclSegment = new ArcSegment 
{ 

Point = tlR, 

Size = new Si ze(rl, rl), 

SweepDirecti on = SweepDirecti on. Clockwise, 
IsLargeArc = true 

}； 

pathFigure.Segments.Add(arclSegment); 
return pathGeometry; 


The remainder of FingerPaint5 should be entirely comprehensible at this point. The 
OnPointerReleosed and OnPointerCaptureLost overrides are the same as FingerPaint4. The internal 
Pointerlnfo class now includes a PreviousRodius field: 


Project: FingerPaint5 I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

struct Pointerlnfo 

{ 

public Brush Brush; 

public Point PreviousPoint; 

public double PreviousRadius; 

} 

Dicti onary<ui nt , PointerInfo> pointerDictionary = new Dicti onary<ui nt , Poi nterInfo>() ; 
Random rand = new RandomO; 
byte[] rgb = new byte [3]; 


public MainPageC) 

{ 

this .InitializeComponent(); 

} 


protected override void OnPointerPressed(Poi nterRoutedEventArgs args) 

{ 

// Get information from event arguments 
uint id = args.Pointer.Pointerld; 

PointerPoint pointerPoint = args.GetCurrentPoi nt(this) ; 
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// Create random color 
rand■NextBytes(rgb); 

Color color = Color. FromArgb(255, rgb[0], rgb[l], rgb[2]); 
// Create Pointerlnfo 

Pointerlnfo pointerlnfo = new Pointerlnfo 

{ 

PreviousPoint = pointerPoint.Position, 

PreviousRadius = 24 * pointerPoint.Properties.Pressure, 
Brush = new Soli dColorBrush(color) 

}； 


// Add to dictionary 

pointerDictionary.Add(id, pointerlnfo); 

// Capture the Pointer 
CapturePointer(args.Poi nter); 
base .OnPointerPressed(args); 


protected override void OnPointerMoved(Poi nterRoutedEventArgs args) 

{ 

// Get ID from event arguments 
uint id = args.Pointer.Pointerld; 

// If ID is in dictionary, start a loop 
if (pointerDictionary.ContainsKey(id)) 

{ 

Pointerlnfo pointerlnfo = pointerDictionary[id]; 

Hist<PointerPoint> pointerpoints = args.GetlntermediatePoi nts(this) ; 

for (i nt i = pointerpoints.Count - 1; i >= 0; i--) 

{ 

PointerPoint pointerPoint = pointerpoints[i]; 

// For each point, create a Path element and add to Grid 
Point point = pointerPoint.Position; 
float pressure = pointerPoint.Properties.Pressure; 
double radius = 24 * pressure; 

Geometry geometry = 

CreateTaperedLineGeometryCpoi nterlnfo.PreviousPoi nt, 

pointerlnfo.PreviousRadius ， 
point ， 
radius); 

Path path = new Path 

{ 

Data = geometry, 

Fill = pointerlnfo.Brush 

}； 

contentGrid.Children.Add(path); 

// Update Pointerlnfo 

pointerlnfo.PreviousPoint = point; 

pointerlnfo.PreviousRadius = radius; 
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// Store Pointerlnfo back in dictionary 
pointerDictionary[id] = pointerlnfo; 


} 

base.OnPoi nterMoved(args); 

} 

protected override void OnPointerReleased(Poi nterRoutedEventArgs args) 

{ 

} 

protected override void OnPointerCaptureLost(Poi nterRoutedEventArgs args) 

{ 

} 

Geometry CreateTaperedLineGeometry(Poi nt cO, double rO, Point cl, double rl) 



And now when you draw even very quickly on a pressure-sensitive device, the lines taper smoothly 
instead of as discrete steps: 



How Do I Save My Drawings? 


None of the finger-painting programs has any facility to save the drawings, but how would you 
implement such a thing? 


Each program draws by adding Polyline or Line or Path elements to a Grid. One way to save your 
drawing would be to access those objects and save all the points and other information in a file, 
perhaps in an XML format. You could then add a feature to load them back in and create new Polyline 
or Line or Path elements from this information. 

But you might be more inclined to save a bitmap of your drawing. (Traditionally, "draw" programs 
work with vectors while "paint” programs work with bitmaps.) Indeed, it makes sense for a FingerPaint 
program to perform oil its painting on a bitmap. 

This is possible, but it’s not as easy as you might think. The easiest approach is to use 
WriteobleBitmap, but you'd have to implement your own line-drawing logic to render lines on that 
bitmap. I’ll show you how in Chapter 14. It’s also possible using DirectX with some C++ coding. That’s 
coming in Chapter 15, "Going Native.’’ 
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Real and Surreal Finger Painting 


In recent years, paint programs have attempted to mimic real-life drawing materials, such as pencil, 
chalk, and water colors. Of course, doing something like this requires combining visual sensitivity and 
programming skill with some degree of randomness. 

You can, of course, go in the opposite direction and render something on the screen that you’ll 
never encounter in the real world. The Whirligig program is very similar in structure to the FingerPaint 
series, but it renders spiraled lines that look like this: 



The Whirligig program implements pointer capture but not Esc-key termination, so the 
OnPointerReleased and OnPointerCoptureLost overrides are the same as in the past couple projects. 
For each finger stroke, the program renders a single Polyline much like the early versions of the 
program, except that Polyline is only one pixel in thickness and it turns around in circles: 

Project: Whirligig I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 
{ 

const double Radi us = 24; // 1/4 inch 

const double Anglelncrement = 0.5; // radians per pixel 

class Touchlnfo 
{ 

public Point LastPoint; 
public Polyline Polyline; 
public double Angle; 

} 

Dictionary<uint, TouchInfo> pointerDictionary = new Dicti onary<ui nt , TouchInfo>() ; 


public MainPage() 
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} 


this .InitializeComponent(); 


protected override void OnPointerPressed(Poi nterRoutedEventArgs args) 

{ 

// Get information from event arguments 
uint id = args.Pointer.Pointerld; 

Point point = args.GetCurrentPoint (this) .Position; 

// Create Polyline 

Polyline polyline = new Polyline 

{ 

Stroke = this .Resources ["ApplicationForegroundThemeBrush"] as Brush , 
StrokeThickness = 1, 

}； 

// Add to Grid 

contentGrid.Chi 1dren.Add(poiyline); 

// Create Touchlnfo 
Touchlnfo touchlnfo = new Touchlnfo 
{ 

LastPoint = point, 

Polyline = polyline 

}； 

// Add to dictionary 

pointerDictionary.Add(id, touchlnfo); 

// Capture the Pointer 
CapturePointer(args■Pointer); 
base. OnPointerPressed(args); 


protected override void OnPointerMoved(Poi nterRoutedEventArgs args) 

{ 

// Get information from event arguments 
uint id = args.Pointer.Poi nterld; 

Point point = args.GetCurrentPoint(this).Position; 

// If ID is not in dictionary, don't do anything 
if (!pointerDictionary.ContainsKey(id)) 
return ; 

// Get Touchlnfo objects 

Polyline polyline = pointerDictionary[id].Polyline; 

Point lastPoint = pointerDictionary[id].LastPoint; 
double angle = pointerDictionary[id].Angle; 

// Distance from last point to this poi nt 

double distance = Math .Sqrt (Math .PowCpoint.X - 1astPoint.X, 2) + 

Math .PowCpoint.Y - 1astPoint.Y, 2)); 

int divisions = (int)di stance; 

for (int i =0; i < divisions; i++) 
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// Sub-divide the distance between the last point and the new 
double x = (i * point.X + (divisions - i) * lastPoint.X) / divisions; 
double y = (i * point.Y + (divisions - i) * lastPoint.Y) / divisions; 
Point pt = new Point (x ， y); 

// Increase the angle 

angle += distance * Anglelncrement / divisions; 

// Rotate the point 

pt.X += Radius * Math ■Cos(angle); 

pt.Y += Radius * Math .Sin(angle); 


// Add to Polyline 
polyline.Points.Add(pt); 


// Save new information 

pointerDictionary[id].LastPoint = point; 

pointerDictionary[id].Angle = angle; 

base.OnPoi nterMoved(args); 

} 


Along with the Polyline itself, the Touch Info class saves a LostPoint value and an Angle value. For 
each PointerMoved event, the program subdivides the distance from the current point to the previous 
point into pixel-sized lengths. For each of these pixel-sized lengths, it appends approximately 30 
degrees of the circular pattern. (The 30 degrees is a result of the Anglelncrement constant.) Instead of 
rendering the actual point, it rotates the point by the accumulated angle and adds it to the Polyline. 


A Touch Piano 


Not all touch applications fall into the same pattern. For example, consider an on-screen piano 
keyboard. Obviously, you want to be able to play chords with your fingers, so this is a job for the 
Pointer events rather than the Manipulation events. 

But what you also really want to do with an on-screen piano keyboard is run your fingers up and 
down the keys making glissandi. If you couldn’t do that with an on-screen keyboard, you would 
undoubtedly consider it broken. What that implies, however, is that you’re probably not exclusively 
concerned with PointerPressed and PointerReleased. Yes, you can press down on one key and release 
on another, but in between you could be playing many other keys just by sweeping your finger. 

There are basically two ways to construct this piano keyboard. You can use one control for the 
whole keyboard, or you can use many controls (and by "many” I really mean one control for each key). 

A single control must draw all the keys and also evaluate PointerMoved events by comparing 
pointer positions with the boundaries of these keys. You’ll be tracking each finger to determine 
when a PointerMoved event indicates a key coming within a key boundary and when it leaves a key 
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boundary. This is classic "hit testing" — you're examining pointer positions to determine if they lie 
within a boundary. 

However, if each key is a separate control, that key doesn’t need to perform hit testing. If it’s 
getting a Pointer event, the Pointer is within the boundaries of that control (unless the control has 
captured the pointer, but pointer capturing makes no sense in this application). 

What Pointer events are necessary to implement a piano key? Don’t start by thinking about presses 
and releases. Think about glissandi. If we’re talking about a keyboard that reacts solely to touch, the 
only two Pointer events that are necessary are PointerEntered and PointerExited. 

However, you probably want the keyboard to respond reasonably to the mouse and pen as well. 

A piano key will get PointerEntered and PointerExited events for a mouse when the mouse button is 
not pressed, and that’s a problem. The PointerEntered handler will need to examine the IsInContact 
property to correctly handle the mouse and pen. That property is always true for touch but only true 
for a mouse if the button is down or for the pen if it’s in contact with the screen. 

Moreover, when considering a single element, the mouse and pen generate PointerEntered events 
before PointerPressed and PointerExited after PointerReleosed, so PointerPressed and PointerReleased 
must be handled as well. 

Let’s construct a two-octave piano keyboard from the bottom up, starting with the keys. The 
following Key class is a Control derivative without a default template, so it has no default visible 
appearance. But it does define an Is Pressed dependency property, and a property-changed handler 
for IsPressed that toggles between two visual states called Normal and Pressed. 

Project: SilentPiano I File: Key.cs (excerpt) 

namespace SilentPiano 
{ 

public cl ass Key : Control 
{ 

static readonly DependencyProperty isPressedProperty = 

DependencyProperty .Register ("IsPressed " ， 
typeof(bool ), typeof (Key) , 

new PropertyMetadata(fal se , OnlsPressedChanged)); 

Li st<uint> pointerList = new Li st<ui nt>() ; 

public static DependencyProperty IsPressedProperty 

{ 

get { return isPressedProperty; } 

} 

public bool IsPressed 

{ 

set { SetValue(IsPressedProperty, value); } 
get { return (bool )GetValue(IsPressedProperty); } 

} 
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} 


protected override void OnPointerEntered(Poi nterRoutedEventArgs args) 

{ 

if (args.Pointer.IsInContact) 

AddToList(args.Pointer■Pointerld); 
base .OnPointerEntered(args); 

} 

protected override void OnPointerPressed(Poi nterRoutedEventArgs args) 

{ 

AddToList(args.Pointer.Pointerld); 
base .OnPointe 「 Pressed(args); 

} 

protected override void OnPointerReleased(Poi nterRoutedEventArgs args) 

{ 

RemoveFromList(args.Pointer.Poi nterld); 
base .OnPointerReleased(args); 

} 

protected override void OnPointerExited(Poi nterRoutedEventArgs args) 

{ 

RemoveFromList(args.Pointer.Pointerld); 
base .OnPointerExited(args); 

} 

void AddToList (ui nt id) 

{ 

if (!pointerList.Contains(id)) 
pointerList.Add(id); 

CheckList(); 

} 

void RemoveFromLi st(ui nt id) 

{ 

if (pointerList.Contains(id)) 
pointerList.Remove(id); 

CheckList(); 

} 

void CheckList() 

{ 

this .IsPressed = pointerList.Count > 0; 

} 


static void OnIsPressedChanged(DependencyObject obj ， 

DependencyPropertyChangedEventArgs args) 


{ 


VisualStateManager .GoToState(obj as Key, 

(bool)args .NewValue ? "Pressed" 


} 


"Normal" , fal se) ; 
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Because you can use two fingers to play the same key, this control still needs to track individual 
fingers. But it doesn't need a Dictionary to retain information for each ID. It can simply use a List. 

IDs are put into this List in the OnPointerEnterecJ override (but only if IsInContact is true) and in 
On Poin ter Pressed, and removed in OnPointerReleased and OnPointerExitecJ, and that triggers the 
change in visual state. The IsPressed property is true if the List contains at least one entry. The 
PointerPressed and PointerReleased event handlers are only for the benefit of the mouse and pen. 

Two templates — one for white keys and one for black keys — are defined in the Octave.xaml file. 
The two templates differ only by the size of a Polygon that defines the key shape and the default 
color. (The shape is a rectangle for both keys. Originally , 丨 wanted to make the various white keys 
different shapes as they are on a real piano, but the uniform approach was a lot easier and required 
far fewer templates.) Both templates switch the color to red during a Pressed state: 


Project: SilentPiano I File: Octave.xaml (excerpt) 

<UserControl … > 

<UserControl.Resources 〉 

<ControlTempi ate x : Key="whi teKey" TargetType="local : Key"> 

<Grid Width="80"> 

〈Polygon Points="2 0, 78 0, 78 320, 02 320"> 

〈 Polygon.Fill 〉 

<SolidColorBrush x:Name="brush" Color="Whi te" /> 
〈 /Polygon.Fill 〉 

</Polygon> 


<VisualStateManager.VisualStateGroups> 

<VisualStateGroup x: Name="CommonStates"> 

<VisualState x : Name="Normal "/> 

<VisualState x : Name="Pressed"> 

<Storyboard> 

<ColorAnimationllsi ngKeyFrames Storyboard .TargetName="brush" 

Storyboard.TargetPrope rty="Col or"> 
<DiscreteColorKeyFrame KeyTime="0" Value="Red" /> 

</ColorAni mati onllsi ngKeyFrames> 

</Storyboard> 

</VisualState> 

</VisualStateGroup> 

</VisualStateManager.VisualStateGroups> 

</Gri d> 

</ControlTemplate> 


<ControlTempi ate x:Key="blackKey" TargetType="local : Key"> 

<Gri d> 

〈Polygon Points="0 0, 40 0, 40 220, 0 220"> 

〈 Polygon.Fill 〉 

<SolidColorBrush x:Name="brush" Color="Bl ack" /> 
〈 /Polygon.Fill> 

</Polygon> 
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<VisualStateManage r.VisualStateGroups> 

<VisualStateGroup x:Name="CommonStates"> 

<VisualState x:Name="Normal "/> 

<VisualState x:Name="Pressed"> 

<Storyboard> 

<ColorAnimationllsi ngKeyFrames Storyboard .TargetName="brush" 

Storyboard.TargetPrope rty="Col or"> 
<DiscreteColorKeyFrame KeyTime="0" Value="Red" /> 

</ColorAni mati onllsi ngKeyFrames> 

</Storyboard> 

</VisualState> 

</VisualStateGroup> 

</VisualStateManager.VisualStateGroups> 

</Grid> 

〈 /ControlTempiate> 

</UserControl.Resources 〉 


<Gri d> 


<StackPanel Orientati on="Hori zontal"> 


<local : Key Tempi ate="{StaticResource 
<local : Key Tempi ate="{StaticResource 
<loca1 : Key Tempi ate="{StaticResource 
<loca1 : Key Tempi ate="{StaticResource 
<local : Key Tempi ate="{StaticResource 
<local : Key Tempi ate="{StaticResource 
<local : Key Tempi ate="{StaticResource 
<local : Key x:Name="lastKey" 

Tempi ate="{StaticResource 
Vi si bility="Col lapsed" /> 


whi teKey}" 
whi teKey}" 
whi teKey}" 
whi teKey}" 
whi teKey}" 
whi teKey}" 
whi teKey}" 

whi teKey}" 


/> 

/> 

/> 

/> 

/> 

/> 

/> 


</StackPanel> 


<Canvas> 


<local : Key Tempi ate="{StaticResource blackKey}" 
Canvas. Left="60" Canvas .Top="0" /> 
<loca1 : Key Tempi ate="{StaticResource blackKey}" 
Canvas. Left="140" Canvas .Top="0" /> 
<loca1 : Key Tempi ate="{StaticResource blackKey}" 
Canvas. Left="300" Canvas .Top="0" /> 
<local : Key Tempi ate="{StaticResource blackKey}" 
Canvas. Left="380" Canvas .Top="0" /> 
<loca1 : Key Tempi ate="{StaticResource blackKey}" 
Canvas. Left="460" Canvas .Top="0" /> 

</Canvas> 


</Gri d> 


</UserControl> 


Eight white keys are arranged horizontally in a StackPanel, but the five black keys are in a Canvas. This 
configuration allows the white keys to define the size of the control but lets the black keys sit on top 
of the white keys and cover parts of them. 

The eight white keys go from C to C. Very often small keyboards start with C and end with C as 
well, but you don’t want a pair of adjacent C keys where two octaves meet up. That’s the reason why 
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the last key has a Visibility of Collapsed. That Visibility property is set to Visible or Collapsed by the 
code-behind file based on the setting of the LostKeyVisible dependency property: 

Project: SilentPiano I File: Octave.xaml.es (excerpt) 

public sealed partial class Octave : UserControl 

{ 

static readonly DependencyProperty 1astKeyVisibleProperty = 

DependencyProperty .Regi ster("LastKeyVisible" , 
typeof(bool ), typeof (Octave) , 

new PropertyMetadata(fal se , OnLastKeyVisibleChanged)); 

public Octave() 

{ 

this. InitializeComponent(); 

} 

public static DependencyProperty LastKeyVisibleProperty 

{ 

get { return 1astKeyVisibleProperty; } 

} 

public bool LastKeyVisible 

{ 

set { SetValue(LastKeyVisibleProperty, value); } 
get { return (bool )GetValue(LastKeyVisibleProperty); } 

} 

static void OnLastKeyVisibleChanged (DependencyObject obj, 

DependencyPropertyChangedEventArgs args) 

{ 

(obj as Octave) .lastKey.Visibility = 

(bool)args .NewValue ? Visibility .Visible : Visibility. Col lapsed; 

} 

} 

All that's left is to instantiate two Octave objects in the MainPage.xaml file, the second one with 
LostKeyVisible set to true: 


Project: SilentPiano I File: MainPage.xaml (excerpt) 

<Page … > 

<Grid Background="Gray"> 

<StackPanel Orientati on="Hori zontal" 

HorizontalAli gnment="Center" 
VerticalAli gnment="Center"> 
<local : Octave /> 

<local : Octave LastKeyVisibl e="True" /> 
</StackPanel> 

</Gri d> 

</Page> 
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And here I am playing my favorite chord (consonant with a major programming language): 



Manipulation, Fingers, and Elements 


The great advantage of the Pointer events is that you can track individual fingers. The great 
advantage of the Manipulation events is that you can’t track individual fingers. 


The Manipulation events combine multiple fingers — and by "multiple” we’re really often talking 
about "two" — into higher-level gestures such as pinch and rotate. These gestures correspond to 
common graphics transforms: translation, scaling (although limited to equal scaling in the horizontal 
and vertical directions), and rotation. Capture is intrinsic to manipulation. As a bonus, inertia is also 
available. 

Keep in mind that multiple fingers are combined into a single series of Manipulation events not 
for the entire window, but for each element handling these events. What this means is that you can 
use a finger or a pair of fingers to manipulate one element, while using another couple fingers to 
manipulate a second element. 

UlElement defines five Manipulation events that an element generally receives in the following 
order (and take heed that the first two have extremely similar names): 

■ ManipulationStarting 

■ ManipulationStarted 


■ ManipulationDelto (many) 

■ Manipulation InertiaStarting 


CHAPTER 13 Touch, Etc 


655 
















■ MonipulotionDelta (more) 

■ ManipulationCompleted 


The Control class defines virtual methods corresponding to these five events named 
OnMonipulotionStorting, and so forth. 

Although the mouse or pen can generate Manipulation events, these occur only when a mouse 
button is pressed or when the pen is touching the screen. A ManipulationStarting event occurs when 
a finger first touches an element, or the mouse button is pressed over an element, or the pen is 
touched to an element. 

The MonipulotionStorted event generally occurs soon after ManipulationStarting (but, as I’ll discuss 
shortly, the key word here is "generally”). What follows is usually a bunch of Manipulation Delta events 
as the fingers move on the screen. When all fingers leave an element, ManipulationlnertiaStarting 
is fired. The element continues to generate MonipulationDelto events representing inertia, but 
ManipulationCompleted indicates that the sequence is over. 

Although the ManipulationStarting event occurs when a finger first touches an element (or a 
mouse click or pen press occurs), this event is not necessarily followed by a MonipulotionStorted event 
and MonipulotionStorted might be delayed a little. The problem is that the system must distinguish 
between a tap or a hold and an actual manipulation. MonipulotionStorted is fired when the finger (or 
mouse or pen) moves a little bit. 

For example, if you touch an element with a sweeping motion, ManipulationStarting is followed 
very quickly by MonipulationStartecJ and multiple MonipulotionDelta events. But put a finger down in 
one place and hold it, and the MonipulotionStorted event can be delayed quite some time. 

If the user taps, or right-taps, or double-taps the screen, a ManipulationStarted event won’t occur 
at all. However, it’s possible for a Holding event to be fired after ManipulationStarting and for the 
user to then move the finger and generate MonipulationStartecJ and the rest of the events. Another 
Holding event is then fired with a HoldingState property indicating Canceled. 

By default, however, an element doesn't generate any Manipulation events whatsoever! The 
Manipulation events must first be enabled on a per-element basis. To allow a program to specify 
exactly what types of manipulation it wants, UlElement defines a ManipulationMode property of 
the enumeration type Manipulation Modes. (The property name is singular; the enumeration name 
is plural.) The default setting of ManipulationMode is Manipulation Modes. System, which for an 
application is equivalent to Manipulation Modes. None. To enable an element for manipulation you’ll 
need to set it to at least one other Manipulation Modes member. The enumeration members are 
defined as bit flags, so you can combine them with the bitwise OR operator (|). 

Although some applications need to handle all five Manipulation events, it’s possible to write code 
that only examines MonipulotionDelta. 

This is the case with the ManipulationTracker program. The program displays a bunch of CheckBox 
controls for the members of the ManipulotionModes enumeration and three Rectangle elements that 


656 PART: Specialties 


you can manipulate. To ease some of the code and markup, a custom CheckBox derivative is used to 
store and display the ManipulationModes members: 

Project: ManipulationTracker I File: ManipulationModeCheckBox.es 

using Windows.UI.Xaml.Controls; 
using Windows.UI.Xaml.Input; 

namespace ManipulationTracker 

{ 

public cl ass ManipulationModeCheckBox : CheckBox 

{ 

public ManipulationModes ManipulationModes { set ; get ; } 

} 


Ten instances of this custom CheckBox are arranged in a StackPonel in MainPage.xaml, each 
identified both with the name of the enumeration member (with spaces inserted in the name to be 
more readable) and the integer value: 


Project: ManipulationTracker | File: MainPage.xaml (excerpt) 

<Page … > 

<Page.Resources> 

<Style TargetType=" local : ManipulationModeCheckBox"> 
〈Setter Property="Margi n" Value="12 6 24 6" /> 
</Style> 


<Style TargetType="Rectangl e"> 

〈Setter Property="Wi dth" Value="144" /> 

〈Setter Property="Hei ght" Value="144" /> 

<Setter Property="Hori zontalA1ignment" Val ue="Left" /> 
〈Setter Property="Verti calA1ignment" Val ue="Top" /> 

〈Setter Property="RenderTransformOri gin" Val ue="0 .5 0.5" /> 
</Style> 

</Page.Resources> 


<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

<Grid.ColumnDefinitions> 

<ColumnDefinition Wi dth="Auto" /> 

<ColumnDefinition Width="*" /> 

</Grid.ColumnDefini ti ons> 

<StackPanel Name="checkBoxPanel " 

Grid.Col umn="0"> 

<1ocal : ManipulationModeCheckBox Checked="OnMani pulationModeCheckBoxChecked" 

Unchecked="OnMani pulationModeCheckBoxChecked" 
Content="Translate X (1)" 

ManipulationModes="T ranslateX" /> 

<1 ocal : ManipulationModeCheckBox Checked="OnMani pulationModeCheckBoxChecked" 

Unchecked="OnMani pulationModeCheckBoxChecked" 
Content="Translate Y (2)" 

ManipulationModes="T ranslateY" /> 
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<1 ocal : ManipulationModeCheckBox Checked="OnMani pulationModeCheckBoxChecked" 

Unchecked="OnMani pulationModeCheckBoxChecked" 
Content="T ranslate Rails X (4)" 

Manipulati onModes="T ranslateRai1sX" /> 

<1 ocal : ManipulationModeCheckBox Checked="OnMani pulationModeCheckBoxChecked" 

Unchecked="OnMani pulationModeCheckBoxChecked" 
Content="T ranslate Rails Y (8)" 

Manipulati onModes="T ranslateRai1sY" /> 

<1 ocal : ManipulationModeCheckBox Checked="OnMani pulationModeCheckBoxChecked" 

Unchecked="OnMani pulationModeCheckBoxChecked" 
Content="Rotate (16)" 

Manipulati onModes="Rotate" /> 

<1 ocal : ManipulationModeCheckBox Checked="OnMani pulationModeCheckBoxChecked" 

Unchecked="OnMani pulationModeCheckBoxChecked" 
Content="Scale (32)" 

Manipulati onModes="Scale" /> 

〈 local : ManipulationModeCheckBox Checked="OnMani pulationModeCheckBoxChecked" 

Unchecked="OnMani pulationModeCheckBoxChecked" 
Content="T ranslate Inertia (64)" 

Manipulati onModes="T ranslatelnertia" /> 

<1 ocal : ManipulationModeCheckBox Checked="OnMani pulationModeCheckBoxChecked" 

Unchecked="OnMani pulationModeCheckBoxChecked" 
Content="Rotate Inertia (128)" 

Manipulati onModes="RotateInerti a" /> 

〈 local : ManipulationModeCheckBox Checked="OnMani pulationModeCheckBoxChecked" 

Unchecked="OnMani pulationModeCheckBoxChecked" 
Content="Scale Inertia (256)" 

Manipulati onModes="Sca1 elnertia" /> 

<1 ocal : ManipulationModeCheckBox Checked="OnMani pulationModeCheckBoxChecked" 

Unchecked="OnMani pulationModeCheckBoxChecked" 
Content="All (OxFFFF)" 

Manipulati onModes="Al1 " /> 

</StackPanel> 

<Grid Name=" rectanglePanel" 

Grid.Col umn="l"> 

〈Rectangle Fi1 l="Red"> 

〈 Rectangle.RenderTransform> 

<CompositeTransform /> 

</Rectangle.RenderTransform> 

</Rectangle> 


〈Rectangle Fi1 l="Green"> 

〈 Rectangle.RenderTransform> 
<CompositeT ransform /> 
〈 /Rectangle.RenderTransform> 
</Rectangle> 
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〈Rectangle Fi1 1="B1 ue"> 

〈 Rectangle.RenderTransform> 
<CompositeTransform /> 
</Rectangle.RenderTransform> 
</Rectangle> 

</Grid> 

</Gri d> 

</Page> 


In the larger cell of the Grid are three Rectangle elements, with the three colors of the state flag of 
Computerstan: red, green, and blue. 

In the code-behind file, any checking or unchecking of the custom CheckBox controls causes a 
calculation of a new Manipulation Modes value by combining enumeration members associated with 
the checked check boxes with the bitwise OR operator. This composite Manipulation Modes value is 
then set to the Mon ip u lotion Mode property of the three Rectangle elements: 

Project: ManipulationTracker I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

public MainPage() 

{ 

this .InitializeComponent(); 

} 

void OnManipulationModeCheckBoxChecked (ob ject sender, RoutedEventArgs args) 

{ 

// Get composite ManipulationModes value of checked CheckBoxes 
ManipulationModes manipulationModes = ManipulationModes .None; 

foreach (UIE1 ement child in checkBoxPanel.Children) 

{ 

ManipulationModeCheckBox checkBox = child as ManipulationModeCheckBox ; 

if ((bool )checkBox.IsChecked) 

manipulationModes |= checkBox.ManipulationModes; 

} 

// Set ManipulationMode property of each Rectangle 
foreach (UIE1 ement child in rectanglePanel.Children) 
child.ManipulationMode = manipulationModes; 

} 

protected override void OnMani pulationDel ta(Mani pulationDeltaRoutedEventArgs args) 

{ 

// OriginalSource is always Rectangle because nothing else has its 
// Mani pul ationMode set to anything other than Manipulati onModes.None 
Rectangle rectangle = args.OriginalSource as Rectangle; 

CompositeT ransform transform = rectangle.RenderT ransform as CompositeT ransform ; 
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transform.TranslateX += args.Delta.Trans1 ation.X; 
transform.TranslateY += args.Delta.Trans1 ation.Y; 

transform.SealeX *= args.Delta.Scale; 
transform.SealeY *= args.Delta.Scale; 

transform.Rotation += args.Delta.Rotation; 

base.OnManipulationDelta(args); 

} 

} 

The final part of the program is the OnMonipulotionDelto override, which is a virtual method defined 
by the Control class that provides easier access to the ManipulotionDelto event defined by UlElement. 
ManipulationDelto is the primary Manipulation event and indicates in what kinds of manipulation the 
user’s fingers are engaged. 

Notice that the OnMonipulotionDelto override casts the OriginolSource property of the event 
arguments to Rectangle without even checking if the cast is successful. In theory, the OriginolSource 
property can be Main Page or any child of Main Page. However, only the Rectangle elements are 
enabled for manipulation, so only the Rectangle elements can generate ManipulotionDelto events. 

The override obtains the CompositeTransform set to the RenderTransform property of that 
particular Rectangle and adjusts five properties of the transform based on the Delta property of the 
event arguments. This Delta property is of type ManipulotionDelto, a structure with four proper¬ 
ties. (Watch out! This structure has the same name as the event that delivers it!) The values indicate 
change since the last ManipulotionDelto event. 

Three of the four ManipulotionDelto properties are accessed by this code. The fourth is Expansion, 
and it’s similar to Scale except expressed in pixels rather than a multiplicative scaling factor. The 
Translation property of the ManipulotionDelto structure indicates the average distance the fingers 
have moved since the last ManipulotionDelto event, so these are just added to the TronsloteX and 
TranslateY properties of the CompositeTransform. If there is no movement, these values are zero. 

Similarly (but handled rather differently), the Scale property of the ManipulotionDelto structure 
indicates the increase in the distance between the fingers since the last event. The ScaleX and ScaleY 
properties of the CompositeTransform are multiplied by this factor. (Because the Manipulation events 
don’t provide separate scaling factors for horizontal and vertical scaling, all manipulation scaling 
is necessarily isotropic — equal in both directions.) If there is no scaling (or scaling has not been 
enabled), the Scale value is 1. The Rotate property of ManipulotionDelto is a change in the rotation 
angle caused by turning the fingers relative to each other, and this is added to the Rotation property 
of CompositeTransform. 
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Check a few check boxes, and you can indeed move the rectangles with the mouse or pen or use 
multiple fingers to move, scale, and rotate the rectangles pretty much as you might expect, even 
manipulating two or three at once: 



For a program using Manipulation events, the rules are very simple: Always set the 
ManipulotionMode property to a non-default value on the element or elements that you want to 
generate Manipulation events. Each element you do this to generates its own independent stream of 
Manipulation events. You can set a handler for the ManipulationDelta event of the element itself, or 
you can handle that event by an ancestor in the visual tree. 


I said that this manipulation works pretty much as you might expect, but it’s not entirely correct. 
You’ll notice that neither the code nor XAML has any reference to centers of scaling or rotation, 
except that RenderTronsformOrigin is set to the relative point (0.5, 0.5). Hence all scaling and rotation 
are relative to the center of each particular rectangle. 


This is not correct behavior. For example, suppose you put one finger near a corner of a rectangle 
and hold it steady. You use a second finger to grab the opposite edge and pull it or rotate it. The 
scaling and rotation that results should be relative to the first finger. In other words, the part of the 
rectangle under that first finger should remain in place while the rest of the rectangle is scaled or 
rotated around it. 


It turns out that fixing this problem takes rather more complex logic, so I’m going to ignore it until 
later in this chapter. 

Meanwhile, you can play with some of the other types of manipulation. There are three types of 
inertia — for translation, scaling, and rotation — and you can indeed flick or spin a rectangle right off 
the screen. There are ways to control the extent of inertia that I’ll discuss later. 
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You can set an equivalent Mon ipula ti on Mo de property shown in the preceding screen shot like this 
in code: 

rectangle.ManipulationMode = ManipulationModes. TranslateX | 

ManipulationModes. TranslateY | 

ManipulationModes. Seale | 

ManipulationModes .Rotate; 

But not in XAML. Setting the MonipulotionMode property in XAML is limited to just a single 
enumeration member, and in a real-life application, that would probably be All. 

If you want to restrict manipulation to horizontal movement only, you can specify the 
MonipulationModes member TronsloteX but not Tran si ateY: 

rectangle.ManipulationMode = ManipulationModes. T ranslateX; 

Similarly, to restrict movement to the vertical, specify TronslateY but not TronsloteX. 

Two of the members of the MonipulationModes enumeration are called TranslateRailsX and 
TransloteRoilsY. These only work as they are intended if you also specify both TronsloteX and 
TransloteY. For example, 

rectangle.ManipulationMode = ManipulationModes .TranslateX | 

ManipulationModes. TranslateY | 

ManipulationModes .TranslateRai1sX; 

This configuration still allows you to freely move the element in the horizontal and vertical directions. 
However, if the manipulation begins with movement in the horizontal direction, the element gets 
stuck in the rails (so to speak) and all further movement is restricted to the horizontal until you lift off 
your finger and start over again. 

Similarly, this configuration restricts movement to the vertical if the manipulation begins with 
vertical movement: 

rectangle.ManipulationMode = ManipulationModes .TranslateX | 

ManipulationModes .TranslateY | 

Mani pul ati onModes .Transl ateRai "I sY; 

You can also specify both: 

rectangle.ManipulationMode = ManipulationModes .TranslateX | 

ManipulationModes .TranslateY | 

ManipulationModes .TranslateRai1sX | 

ManipulationModes .TranslateRai1sY; 

Begin dragging the element diagonally, and you can move it any which way. But begin with horizontal 
or vertical movement, and the element gets stuck in the rails. 

As you saw earlier in the code listing, the ManipulationTracker program uses the Delta property of 
the Manipulation Delta Routed EventArgs argument to make changes to a CompositeTransform: 

transform.TranslateX += args.Delta.Translation.X; 
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transform.TranslateY += args.Delta.Translation.Y; 

transform.SealeX *= args.Delta.Scale; 
transform.SealeY *= args.Delta.Scale; 

transform.Rotation += args.Delta.Rotation; 

If youVe examined the properties of Manipulation Delta Routed EventArgs, youll have discovered 
that besides the Delta property there is a Cumulative property, also of type MonipulotionDelto. The 
Delta property indicates change since the last ManipulationDelto event, but Cumulative indicates 
change since ManipulotionStarted. 

You might suspect that this Cumulative property is easier to work with than the Delta property 
because you can just transfer the values to the corresponding properties of the CompositeTronsform, 
like this: 

transform.TranslateX = args.Cumulative.Translation.X; 
transform.TranslateY = args.Cumulative.Translation.Y; 

transform.SealeX = args.Cumulative.Scale; 
transform.SealeY = args.Cumulative.Scale; 

transform.Rotation = args.Cumulative.Rotation; 

With this code, the first time you manipulate an element, it seems to work just fine. But lift your 
fingers off and try another manipulation on the same element. The element jumps back to its original 
position in the upper-left corner of the screen! 

The Cumulative property is not cumulative from the beginning of the program but only from a 
particular ManipulotionStarted event. 

Working with Inertia 

The Manipulation events support inertia for translation, scaling, and rotation, but if you don’t want 
inertia, simply don’t specify those Manipulation Modes. 

If at any time you want to stop the manipulation or the inertia, the event arguments accompanying 
the ManipulotionStarted and ManipulationDelto events have a Complete method, which causes a 
firing of the Manipulation Completed event. 


If you’d like to handle inertia on your own, you can do that as well. The event arguments 
accompanying the ManipulationDelto and ManipulationInertioStorting events have a Velocities 
property that indicates the linear, scaling, and rotational velocities. For linear movement, the Velocities 
property is in pixels per millisecond, which I suspect aren’t exactly intuitive units. As I experimented 
with giving on-screen objects a good flick with my finger, I came close to 10 pixels per millisecond but 
could never get it higher than that. That’s 10,000 pixels per second, which is equivalent to about 100 
inches per second, or about 8 feet per second, or not quite 6 miles per hour. 
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Default deceleration is provided, but if you’d like to set your own you need to handle the 
ManipulotionlnertiaStarting event. The ManipulotionlnertioStartingRoutedEventArgs class defines 
these three properties: 

■ Translation Behavior of type I nertioTronslation Behavior 

■ ExpansionBehovior of type Inertia Expansion Behavior 

■ RotationBehovior of type Inertia Rotation Behavior 

The InertiaTronslationBehavior class (for example) lets you set linear deceleration in two ways: with 
a Desired Displacement property in units of pixels (which is how much farther you want the object to 
travel) or a Desired Deceleration property in units of pixels per millisecond squared. Both properties 
have default values of NaN (not a number). 

The Desired Deceleration values are generally very small, but perhaps a physics review is in order 
here. 

From basic physics, we know that with a constant acceleration applied to an object at rest, the 
distance the object travels in time t is 

1 2 

x 二一 at 

2 

For example, an object in free fall near the surface of the Earth without air resistance experiences a 
constant acceleration of 32 feet per second per second, or 32 feet per second squared. Set a to 32, 
and you can calculate that the object falls 16 feet at the end of 1 second, a total of 64 feet at the end 
of 2 seconds, and a total of 144 feet at the end of 3 seconds. 

The velocity v is calculated as the first derivative of the distance with respect to time: 

dx 

v = —— =at 
dt 

Again, for an object in free fall, the velocity is 32 feet per second at the end of 1 second, 64 feet per 
second at the end of 2 seconds, and 96 feet per second at the end of 3 seconds. Every second the 
velocity increases by 32 feet per second. 

Deceleration is the same process in reverse. From that second formula we know that 


v 

Cl —— 

t 

If an object is traveling at velocity v, a constant deceleration a will bring it to rest in t seconds. If 
an on-screen object is traveling at the rate of 5 pixels per millisecond, you can use this formula to 
calculate a deceleration necessary to stop it in a fixed number of seconds, for example, 5 seconds or 
5000 milliseconds: 


a 


5000 


0.001 pixels / msec 


2 
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The FlickAndBounce project makes a similar calculation, except that the deceleration time is set 
via a Slider and can range from 1 second to 60 seconds. The XAML file includes that Slider and also an 
Ellipse with a MonipulotionMode setting and three Manipulation events. Although MonipulotionMode 
is set to All (because there's not much of an alternative in XAML), the program uses translation 
only and moves the Ellipse by setting Canvas .Left and Canvas .Top attached properties rather than a 
transform: 


Project: FlickAndBounce I File: MainPage.xaml (excerpt) 

<Page … > 

<Grid Name="contentGri d" 

Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

<Canvas> 

〈Ellipse Name="el 1ipse" 

Fill="Red" 

Width="144" 

Hei ght="144" 

ManipulationMode="Al 1" 

Manipulati onStarted="OnEl 1ipseManipulati onStarted" 

ManipulationDel ta="0nEl 1ipseManipulationDelta" 

ManipulationlnertiaStarti ng="0nEl1 ipseManipulationlnertiaStarting" /> 

</Canvas> 


〈Slider x:Name="slider" 

Val ue="5" Minimum="l" Maximum="60" 

VerticalAli gnment="Bottom" 

Margin="24 0" /> 

</Gri d> 

</Page> 

Of course, any deceleration would be wasted if the object just skittered off past the edge of the 
screen. For that reason, the MonipulationDelto handler detects when the Ellipse has moved past the 
edges of the screen. It moves the Ellipse back into view as if it’s bounced off the edge and reverses 
further movement using the xDirection and YDirection fields. 

Notice that this logic uses the Islnertial property for the bounce logic. It doesn’t stop you from 
dragging the Ellipse past the edges of the screen: 

Project: FlickAndBounce I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

int xDirecti on; 
int yDirecti on; 

public MainPage() 

{ 

this. Ini ti alizeComponent(); 

} 

void OnEllipseManipulationStarted (object sender, ManipulationStartedRoutedEventArgs args) 
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// Initialize directions 
xDirecti on = 1; 
yDirecti on = 1; 


void OnEl1ipseManipulationDel ta(ob ject sender, ManipulationDeltaRoutedEventArgs args) 

{ 

// Find new position of ellipse regardless of edges 

double x = Canvas .GetLeft(el1ipse) + xDirecti on * args.Delta.Translation.X; 
double y = Canvas .GetTop(el1ipse) + yDirecti on * args.Delta.Translation.Y; 


if (args.Islnertial) 

{ 

// Bounce it off the edges 

Size playground = new Si ze(contentGrid.ActualWidth - ellipse.Width, 

contentGricL Actual Height - el 1ipse.Height); 


while (x < 0 || y < 0 || x > piayground.Width || y > playground.Height) 

{ 

if (x < 0) 

{ 

x = -x; 

xDirecti on *= -1; 

} 

if (x > piayground.Width) 

{ 

x = 2 * piayground.Width - x; 
xDirecti on *= -1; 

} 

if (y < 0) 

{ 

y = -y; 

yDirecti on *= -1; 

} 

if Cy > piayground.Height) 

{ 

y = 2 * piayground.Height - y; 
yDirecti on *= -1; 


Canvas .SetLeft(el 1ipse, x); 
Canvas .SetTopCel1ipse, y); 


void OnEl1ipseManipulationlnertiaStarti ngCobject sender, 

ManipulationlnertiaStartingRoutedEventArgs args) 


{ 


double maxVelocity = Math .Max (Math .Abs(args.Velocities.Linear.X), 

Math .Abs(args.Velocities.Li near.Y)); 


} 


args.TranslationBehavior.DesiredDeceleration = maxVelocity / (1000 * slider.Value); 
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In the MonipulotionlnertiaStorting handler down at the bottom, the maximum of the absolute values 
of the horizontal and vertical velocities is used to calculate a deceleration based on a Slider value in 
seconds. 


An XYSlider Control 


An XYSlider control is similar to a Slider except that it allows you to select a point in a two-dimensional 
surface by changing the location of a crosshair (or something similar). At first, it seems like the Pointer 
events would be fine for this control, until you realize that the control really doesn’t want to deal with 
multiple fingers. If it used the Manipulation events instead, it could avoid all that. 

That was my original thought, anyway. But let’s try it. 

I derived XYSlider from ContentControl so that it could display whatever you wanted as a 
background simply by setting the Content property. Sitting on top of that is a crosshair that you 
move around with a finger, mouse, or pen. The control has one property, Value of type Point, and 
a VolueChonged event. The X and Y coordinates of the Point property are normalized to the range 
0 to 1 relative to the content, which relieves the control of defining Minimum and Maximum val¬ 
ues like RongeBase or an IsDirectionReversed property like Slider. (Actually, it would need a pair of 
IsDirectionReversed properties for the X and Y axes.) 

The control definition itself is templateless, but it wants two parts in the template: the customary 
ContentPresenter normally found in a ContentControl template, and something that visually resembles 
a cross-hair. This cross-hair is moved around by code using Canvas.Left and Convos.Top attached 
properties, strongly suggesting that the template needs to define this cross-hair in a Canvas. 


Project: XYSliderDemo | File: XYSIider.es 

namespace XYSliderDemo 
{ 

public cl ass XYSlider : ContentControl 
{ 

ContentPresenter ContentPresenter; 

FrameworkEIement crossHairPart; 

static readonly DependencyProperty valueProperty = 

DependencyProperty .Regi ster("Val ue" , 

typeof (Point) , typeof (XYS1 i der) , 

new PropertyMetadata (new Poi nt(0 .5, 0.5), OnValueChanged)); 

public event EventHandler<Point> ValueChanged; 

public XYSliderO 
{ 

this.DefaultStyleKey = typeof (XYS1 i der) ; 

} 

public static DependencyProperty ValueProperty 
{ 

get { return valueProperty; } 
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} 


public Point Value 

{ 

set { SetValue(ValueProperty, value); } 

get { return (Poi nt)GetValue(ValueProperty); } 

} 


protected override void OnApplyTemplate() 

{ 

// Detach event handlers 
if (contentPresenter != null) 

{ 

contentPresenter.ManipulationStarted -= OnContentPresenterManipulationStarted; 
contentPresenter.ManipulationDelta -= OnContentPresenterManipulationDelta; 
contentPresenter.SizeChanged -= OnContentPresenterSizeChanged; 


// Get new parts 

crossHairPart = GetTemplateChi ld("CrossHairPart") as FrameworkElement ; 
contentPresenter = GetTemplateChiId ("ContentPresenterPart") as ContentPresenter ; 

// Attach event handlers 
if (contentPresenter != null) 

{ 

contentPresenter.ManipulationMode = ManipulationModes .TranslateX | 

ManipulationModes .TranslateY; 

contentPresenter.ManipulationStarted += OnContentPresenterManipulationStarted; 
contentPresenter.ManipulationDelta += OnContentPresenterManipulationDelta; 
contentPresenter.SizeChanged += OnContentPresenterSizeChanged; 


// Make cross-hair transparent to touch 
if (crossHairPart != null) 

{ 

crossHairPart.IsHitTestVisible = false; 


base. OnApplyTempl ateO; 


} 


void OnContentPresenterManipulationStarted (object sender, 

ManipulationStartedRoutedEventArgs args) 

{ 

RecalculateValue(args.Position); 

} 


void OnContentPresenterManipulationDelta (object sender, 

ManipulationDeltaRoutedEventArgs args) 

{ 

RecalculateValue(args.Position); 

} 


void OnContentPresenterSizeChanged (object sender, SizeChangedEventArgs args) 
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{ 

SetCrossHair(); 

} 

void RecalculateVal ue(Poi nt absolutePoint) 

{ 

double x = Math .Max(0, Math .Min(1, absolutePoint.X / contentPresenter.ActualWidth)); 
double y = Math .Max(0, Math .Min(1, absolutePoint.Y / contentPresenter.ActualHeight)); 
this .Value = new Poi nt(x, y); 

} 

void SetCrossHair() 

{ 

if (contentPresenter != null && crossHairPart != null) 

{ 

Canvas. SetLeft(crossHairPart, this .Value.X * contentPresenter.ActualWidth); 
Canvas. SetTopCcrossHairPart, this. Value.Y * contentPresenter.ActualHeight); 

} 

} 

static void OnVal ueChanged(DependencyObject obj, 

DependencyPropertyChangedEventArgs args) 

{ 

(obj as XYS1i der) .SetCrossHai r(); 

(obj as XYS1i der) .OnValueChanged((Point)args.NewValue); 

} 

protected void OnValueChanged(Poi nt value) 

{ 

if (ValueChanged != null) 

ValueChanged(thi s , value); 

} 



When the Value property is set programmatically, the class must set the cross-hair to the correct 
position by multiplying the width and height of the ContentPreseriter by the relative coordinates. This 
happens in the SetCrossHair method. The ManipulationStarted and MonipulationDelto event handlers 
are set on the ContentPreseriter object. Both call the RecalculateValue method to convert the absolute 
coordinates of the pointer to relative coordinates for the Value property. 

The MonipulotionStorted and MonipulationDelto handlers both reference a property of the event 
arguments named Position, which I haven’t mentioned yet. For a mouse or pen, this Position prop¬ 
erty is simply the location of the mouse pointer or pen tip relative to the control generating these 
Manipulation events — the ContentPreseriter in this case. For touch, the Position property is the aver¬ 
age location of all the fingers involved in the manipulation. It provides a convenient way to deal with 
multiple fingers when you really want the position of only one finger. 


CHAPTER 13 Touch, Etc. 


669 


The MainPage.xaml file instantiates an XYSlider and references a flattened map of the Earth that I 
obtained from a NASA website. But most of the XAML file is dedicated to defining a template for the 
XYSlider and particularly the cross-hair. Notice that I put the Con ten t Presenter and the Canvas in a 
Grid and assigned some properties to the Grid normally assigned to the Con ten t Presen ter. This means 
that the upper-left corners of the ContentPresenter and Convos are aligned, which makes it easier to 
convert between ContentPresenter coordinates and relative coordinates: 


Project: XYSliderDemo | File: MainPage.xaml (excerpt) 

<Page … > 

<Page.Resources 〉 

<ControlTempi ate x : Key="xySl iderTemplate" TargetType="l ocal : XYS1ider"> 

〈Border BorderBrush="{Templ ateBinding BorderBrush}" 

BorderThickness=" {TempiateBinding BorderThi ckness}" 

Background=" {TempiateBinding Background }"〉 

<Grid Margi n="{Templ ateBi ndi ng Padding}' 1 

HorizontalAli gnment=" {TempiateBinding HorizontalContentAlignment}" 
VerticalAli gnment=" {TempiateBinding VerticalContentAlignment }"> 


〈ContentPresenter N ame="Conten tPresenterPart" 

Content=" {TempiateBinding Content}" 

ContentTemplate="{Templ ateBinding ContentTemplate}" /> 

<Canvas> 

<Path Name="CrossHai rPart" 

Stroke="{TemplateBinding Foreground}" 

StrokeThickness="3" 

Fi1 l="Transparent"> 

〈 Path.Data> 


<GeometryGroup FillRul e="Nonzero"> 

<E11ipseGeometry Radi usX="48" RadiusY="48" /> 

<E11ipseGeometry Radi usX="6" RadiusY="6" /> 

<LineGeometry StartPoi nt="-48 0" EndPoint="-6 0" /> 
<LineGeometry StartPoi nt="48 0" EndPoint="6 0" /> 
<LineGeometry StartPoi nt="0 -48" EndPoi nt="0 -6" /> 
<LineGeometry StartPoi nt="0 48" EndPoi nt="0 6" /> 
</GeometryGroup> 

〈/Path _ Data> 

</Path> 

</Canvas> 

</Grid> 

</Border> 

</ControlTemplate> 


〈Style TargetType=" local : XYSlider "〉 

〈Setter Property="Templ ate" Val ue="{StaticResource xySliderTempl ate}" /> 
</Style> 

</Page.Resources 〉 


<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Grid.RowDefinitions> 

〈RowDefinition Height:"*" /> 

〈RowDefinition Height="Auto" /> 

</Grid.RowDefinitions> 
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〈 local : XYSlider x:Name="xySlider" 

Grid.Row="0" 

Margin="48" 

Val ueChanged="OnXYSl iderValueChanged"> 

<!-- Image courtesy of NASN/DPL-Caltech (http://maps.jpl.nasa.gov)--> 
<Image Source="Images/earOxuu2 .jpg" /> 

〈 /local : XYS1ider> 

<TextBlock Name="l abel" 

Grid.Row= ,, l" 

Style="{StaticResource SubheaderTextStyle}" 

HorizontalAli gnment="Center" /> 

</Gri d> 

</Page> 


The code-behind file has a handler for the ValueChonged event of XYSlider and uses that to display 
the corresponding longitude and latitude. Just to check that the code works the other way, it also 
uses the Geolocator class to obtain the current geographical location of the computer on which the 
program is running: 


Project: XYSliderDemo | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

bool manual Change = false; 

public MainPage() 

{ 

this .InitializeComponent(); 

// Initialize position of cross-hair in XYSlider 
Loaded += async (sender, args)=> 

{ 

Geolocator geolocator = new Geolocator() ; 

// Might not have permission! 
try 

Geoposition position = await geolocator.GetGeopositionAsync(); 

if (!manual Change) 

{ 

double x = (position.Coordinate.Longitude + 180) / 360; 
double y = (90 - position.Coordinate.Latitude) / 180; 
xySlider.Value = new Point (x ， y); 

} 

} 

catch 


}； 

} 

void OnXYSliderValueChanged (object sender, Point point) 
{ 

double longitude = 360 * point.X - 180; 
double latitude = 90 - 180 * point.Y; 
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} 


label.Text = String. Format ("Longitude: {0:F0} Latitude: {1:F0 }"， 

longitude, latitude); 

manualChange = true; 


Using the Geolocator class requires that you edit the Package.appxmanifest class to request 
Location capabilities. In Visual Studio, select the Package.appxmanifest file, select the Capabilities 
tab, and click Location. At run time, Windows 8 will then ask the user if it’s OK for the program to 
know the computer's location. If the user denies permission, the GetGeopositionAsync call raises an 
exception. 

Here’s how it looks: 



In an earlier version of this control that I wrote for Windows Phone 7, I used a templated Thumb for 
the cross-hair. I wasn’t happy with that version because it required the user to drag the Thumb from 
its current location to a new location. For this new version, I wanted the cross-hair to snap to a new 
position with a simple touch. 

But rm not sure this version entirely succeeds either. As I mentioned earlier (and as you’ll 
experience), simply touching a location does not snap the cross-hair to that point because some 
movement is required before the ManipulotionStorted event is fired. 


At first I thought I could make it respond faster by substituting a PointerPressed event for the 
ManipulotionStorted event. However, apparently the simple act of calling GetCurrentPoint on the 
PointerRoutedEventArgs object inhibits Manipulation events. 

Perhaps this is a case where the Pointer events are really best, and if there are multiple fingers 
attempting to move the crosshair they should just be averaged together. I wouldn’t be surprised if 
there’s a better version oi XYSIider in the next chapter, when it’s used for a color-selection control in a 
bitmap-based finger-painting program. 
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Centered Scaling and Rotation 

When I first introduced the scaling and rotation features of the Manipulation events, I mentioned 
that applying these transforms with reference to a center point was a little tricky. Yet, in many cases 
it’s important. The satisfaction of a touch interface depends a lot on how close the connection feels 
between a user’s fingers and on-screen objects. 

There is a technique to determine the scaling and rotation center involving the Position property 
that I used in the last section. This property is the average of the positions of all the fingers relative 
to the element being manipulated. It is not the center of scaling and rotation, but it can be used to 
derive that center. 

The CenteredTransforms project has a XAML file that references a bitmap on my website: 


Project: CenteredTransforms I File: MainPage.xaml (excerpt) 

<Page … > 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Image Name="image" 

Sou rce="http: //www. charl espetzold. com/pw6/Petzol d Jersey ■ ]_ pg" 
Stretch="None" 

HorizontalAli gnment="Left" 

VerticalAli gnment="Top"> 

<Image.RenderTransform> 

<T ransformGroup x: Name="xformGroup"> 

<MatrixTransform x: Name="matrixXform" /> 

<CompositeTransform x : Name="composi teXform" /> 

</TransformGroup> 

</Image.RenderTransform> 

</Image> 

</Gri d> 

</Page> 


Notice that the RenderTronsform property is now set to a TronsformGroup containing both a 
MatrixTransform and a CompositeTransform. 

The code-behind file enables all forms of Manipulation except those involving rails: 


Project: CenteredTransforms I File: MainPage.xaml.es (excerpt) 


public sealed partial class MainPage : Page 


public MainPageO 


this. Ini ti alizeComponent(); 

image.ManipulationMode = ManipulationModes .Al1 & 

~ManipulationModes .TranslateRai1sX & 
~ManipulationModes .TranslateRai1sY; 


protected override void OnManipulationDelta(Mani pulationDeltaRoutedEventArgs args) 

{ 

// Make this the entire transform to date 
matrixXform.Matrix = xformGroup.Value; 
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// Use that to transform the Position property 

Point center = matrixXform.TransformPoint(args.Position); 

// That becomes the center of the new incremental transform 
compositeXform.CenterX = center.X; 
compositeXform.CenterY = center.Y; 

// Set the other properties 

compositeXform.Trans!ateX = args.Delta.Trans1ation.X; 
compositeXform.TranslateY = args.Delta.Translation.Y; 
compositeXform.SealeX = args.Delta.Scale; 
compositeXform.SealeY = args.Delta.Scale; 
compositeXform.Rotation = args.Delta.Rotation; 

base.OnManipulationDelta(args); 

} 

} 

The On Manipulation Delta override juggles around the three transform objects defined in the 
XAML file. At any time, the Value property of the TransformGroup (which is a Matrix value) represents 
the entire transform, which is the product of the transforms represented by the MatrixTransform 
and CompositeTronsform objects. The ManipulationDelta handler first sets the Matrix value from 
the TransformGroup to the MatrixTransform, which means that the MatrixTransform \s now the 
entire transform up to this point. This transform is also applied to the Position property, and 
that becomes the CenterX and CenterY properties for the CompositeTronsform. The new values 
from the ManipulationDelta structure can then be set directly to the other properties of the 
CompositeTronsform. 

Does it work? You’ll definitely want to try it out because you can’t tell from this screen shot: 



Try holding one finger still on a corner and pulling the opposite corner away or rotate it, and you'll 
see that the image follows your fingers — given the restriction of the isotropic scaling, of course. 
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To make this technique a little easier to use, I wrote a tiny class called MonipulotionManoger that 
performs this calculation in its own private collection of transforms created in the constructor and 
saved in fields: 


Project: ManipulationManagerDemo | File: ManipulationManager.es 

using Windows.Foundation; 
using Windows.UI.Input; 
using Windows.UI.Xaml.Media; 


namespace ManipulationManagerDemo 

{ 

public cl ass ManipulationManager 

{ 

TransformGroup xformGroup; 

MatrixTransform matrixXform; 

CompositeTransform compositeXform; 

public ManipulationManager() 

{ 

xformGroup = new TransformGroupO ; 
matrixXform = new MatrixTransform() ; 
xformGroup.Chi Idren.Add(matrixXform); 
compositeXform = new CompositeTransform() ; 
xformGroup.ChiIdren.Add(compositeXform); 
this .Matrix = Matrix. Identity; 

} 

public Matrix Matrix { private set; get ; } 

public void AccumulateDel ta(Poi nt position, ManipulationDelta delta) 

{ 

matrixXform.Matrix = xformGroup.Value; 

Point center = matrixXform.TransformPointCposition); 

compositeXform.CenterX = center.X; 

compositeXform.CenterY = center.Y; 

compositeXform.TranslateX = delta.Translation.X; 

compositeXform.TranslateY = delta.Translation.Y; 

compositeXform.SealeX = delta.Seale; 

compositeXform.SealeY = delta.Seale; 

compositeXform.Rotation = delta.Rotation; 

this. Matrix = xformGroup.Value; 

} 



The public AccumulateDelto method accepts a ManipulotionDelto value directly and calculates a new 
Matrix property. This allows elements that must be manipulated in this way to have only a single 
transform: 


Project: ManipulationManagerDemo | File: MainPage.xaml (excerpt) 

<Page … > 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Image Name="image" 

Sou rce="http: //www.charlespetzold.com/pw6/PetzoldJersey.jpg" 
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Stretch="None" 


HorizontalAli gnment="Left" 

VerticalAli gnment="Top"> 

<Image.RenderTransform> 

<MatrixTransform x : Name="matri xXform" /> 
</Image.RenderTransform> 

</Image> 

</Gri d> 

</Page> 


The code-behind file creates an instance of Manipulation Manager and uses that to calculate a new 
transform for the Image: 


Project: ManipulationManagerDemo | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

ManipulationManager manipulationManager = new ManipulationManager() ; 

public MainPage() 

{ 

this. InitializeComponent(); 

image.ManipulationMode = ManipulationModes .A11 & 

〜 ManipulationModes .TranslateRai IsX & 

〜 ManipulationModes .TranslateRai1sY; 

} 

protected override void OnManipulationDel ta(Mani pulationDeltaRoutedEventArgs args) 

{ 

manipulationManager.AccumulateDelta(args.Position ， args.Delta); 
mat rixXfo rm.Mat rix = manipulationManager.Matrix; 
base. OnManipulationDelta(args); 

} 

} 


If you had multiple manipulable objects on the screen, you’d need an instance of 
Manipulation Manager for each one. In the next chapter I’ll use a variation of Manipulation Manager in 
a PhotoScatter project that displays the images in your Pictures directory and lets you pore through 
them with your fingers. 


Single-Finger Rotation 


Although the ManipulotionStorting event doesn’t necessarily signal that a manipulation will actually 
occur, it offers a few ways for a program to initialize the manipulation, all involving properties of 
MonipulationStarting Routed EventArgs: 

■ The Mode property is of the familiar enumeration type Manipulation Modes, and here it lets 
you set the types of manipulation you want to handle. But keep in mind that you’ll get a 
ManipulotionStorting event only if the element has its Man ip u lotion Mode property set to 
something other than Manipulation Modes. None or MonipulotionModes.System. 
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■ The Container property is read-only in all the other Manipulation events but writeable 
in the MonipulotionStorting event. By default, the Container property is the same as the 
OriginalSource property, but in later events it’s the element that the Position property 
is relative to. If you want the Position property to be relative to an element other than 
OriginalSource, set the Container property to that element. 

■ The Pivot property enables single-finger rotation, and that’s what 111 show you here. 

Suppose a photograph is sitting on a table, (「m referring here to a real photograph sitting on a 
real table.) You touch your finger to a corner and pull it toward you. Does the photograph stay in the 
same orientation? Not necessarily. If you’re touching it fairly lightly, friction between the table and 
photograph causes the photograph to rotate a bit and the rest of it drags behind the corner that 
you’re pulling. 

You get a similar effect with single-finger rotation, but you need to use the technique I just 
showed you for rotating objects around a center. Indeed, this XAML file is basically the same as the 
CenteredTransforms project: 

Project: SingleFingerRotate | File: MainPage.xaml (excerpt) 

<Page … > 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

<Image Name="image" 

Sou rce="http: //www.charlespetzold.com/pw6/PetzoldJersey.jpg" 

Stretch="None" 

HorizontalAli gnment="Left" 

VerticalAli gnment="Top" 

RenderTransformOrigi n="0 0"> 

<Image.RenderTransform> 

<T ransformGroup x: Name="xformGroup"> 

<MatrixTransform x : Name="matri xXform" /> 

<CompositeTransform x : Name="composi teXform" /> 

</TransformGroup> 

</Image.RenderTransform> 

</Image> 

</Gri d> 

</Page> 

The code-behind file is nearly identical as well with the exception of the OnManipulationStarting 
override: 

Project: SingleFingerRotate | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

public MainPage() 

{ 

this .InitializeComponent(); 

image.ManipulationMode = ManipulationModes .Al1 & 

~Mani pul ati onModes .Transl ateRai "I sX & 

〜 ManipulationModes .TranslateRai1sY; 

} 
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protected override void OnManipulationStarting (ManipulationStartingRoutedEventArgs args) 


args.Pivot = new ManipulationPi vot(new Point (image.ActualWidth / 2 ， 

image.ActualHeight / 2), 

50); 

base. OnManipulationStarting(args); 

} 

protected override void OnManipulationDelta(Mani pulationDeltaRoutedEventArgs args) 

{ 

// Make this the entire transform to date 
matrixXform.Matrix = xformGroup.Value; 

// Use that to transform the Position property 

Point center = matrixXform.TransformPoint(args.Position); 

// That becomes the center of the new incremental transform 
compositeXform.CenterX = center.X; 
compositeXform.CenterY = center.Y; 

// Set the other properties 

composi teXform .Trans"! ateX = args.Delta.Translation.X; 
composi teXform.TranslateY = args.Delta.Translation.Y; 
compositeXform.SealeX = args.Delta.Scale; 
compositeXform.SealeY = args.Delta.Scale; 
compositeXform.Rotation = args.Delta.Rotation; 

base. OnManipulationDelta(args); 

} 

} 

The key here is setting the Pivot property of the ManipulationStartingRoutedEventArgs object to a 
MonipulationPivot object. This object provides two things: 

■ A center of rotation, almost always the center of the object being manipulated 

■ A protection radius around the center, here set to 50 pixels 

Without that second item your finger can get very close to the center of the element, whereupon just 
a little movement can give it a big spin. 

This is one of those programs you really have to try out for yourself to get a feel for how 
single-finger rotation adds some realism to the dragging operation. 

Remember the SliderSketch program from Chapter 5, "Control Interaction ”？ Remember how you 
asked, "Shouldn’t these be dials rather than sliders ?’’？ The DialSketch program that concludes this 
chapter uses a Dial control that incorporates single-finger rotation. 

To make the Dial class a little easier to define, I decided it should derive from RangeBose just like 
Slider. This gives the control Minimum, Maximum, and Value properties all of type double, as well as 
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a VolueChongecJ event. The double values in this control, however, are rotation angles, and the only 
enabled manipulation mode is rotation: 


Project: DialSketch I File: Diai.cs 

using System; 

using Windows■Foundation; 

using Windows.UI.Xaml.Controls•Primitives; 

using Windows.UI.Xaml .Input; 


namespace DialSketch 

{ 

public cl ass Dial : RangeBase 

{ 

public Di al() 

{ 

ManipulationMode = ManipulationModes .Rotate; 

} 

protected override void OnManipulationStarting (ManipulationStartingRoutedEventArgs args) 

{ 

args.Pivot = new ManipulationPi vot(new Poi nt(thi s .ActualWidth / 2, 

this .ActualHeight / 2 )， 

48); 

base .OnManipulationStarting(args); 

} 

protected override void OnManipulationDel ta(Mani pulationDeltaRoutedEventArgs args) 

{ 

this. Value = Math .Max (thi s .Minimum, 

Math .Min (this .Maximum, this .Value + args.Delta.Rotation)); 

base .OnManipulationDelta(args); 

} 

} 


That’s it! Of course, it doesn’t have a template yet, nor does it access any transforms. It just sets a 
new Value property (which causes RangeBase to fire a ValueChonged event), and it expects everything 
else to be implemented elsewhere. 

Two of these Dial controls are instantiated in the XAML file for DialSketch. The Resources section 
is devoted to supplying a Style for these two controls, including a ControlTemplate. The Dial control 
require visuals that let the user know it’s rotating, so the template uses a dashed line with very short 
dashes to simulate tick marks. 
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Notice the Minimum and Maximum values set on the Dial. These imply that the Dial can be 
rotated 10 full times between its minimum and maximum positions. To draw a line from one edge of 
the DialSketch canvas to the opposite edge, you need to turn the dial 10 times: 


Project: DialSketch | File: MainPage.xaml (excerpt) 

<Page … > 

<Page.Resources 〉 

<Style TargetType="l ocal : Dial"> 

〈Setter Property="Mi nimum" Val ue="-1800" /> 

<Setter Prope rty="Maxi mum" Value="1800" /> 

〈Setter Property="RenderT ransformOrigin" Val ue="0 .5 0.5" /> 
〈Setter Property="Wi dth" Value="144" /> 

〈Setter Property="Hei ght" Value="144" /> 

〈Setter Property="Margi n" Value="24" /> 

〈Setter Prope rty="Templ ate"> 

<Setter.Value> 

<ControlTemplate> 

<Grid> 

〈Ellipse Fill="DarkRed M /> 

〈Ellipse Stroke="Black" 

StrokeThi ckness="12" 
StrokeDashArray="0 .1 1" 

Margin="3" /> 

〈Ellipse Fill="Black" 

Width="6" 

Height="6" /> 

</Grid> 

〈/ControlTempi ate> 

</Setter.Value> 

</Setter> 

</Style> 

</Page.Resources 〉 


<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Grid.RowDefinitions> 

<RowDefinition Height:"*" /> 

< RowDefinition Hei ght="Auto" /> 

</Grid.RowDefinitions> 

<Grid.ColumnDefiniti ons> 

<ColumnDefinition Wi dth="Auto" /> 

<ColumnDefinition Width="*" /> 

<ColumnDefinition Width="Auto" /> 

</Grid.ColumnDefiniti ons> 

〈Border Grid. Row="0" 

Grid.Column="0" 

Grid.ColumnSpan= '3' 

BorderBrush="{Stati cResource ApplicationForegroundThemeBrush} 
BorderThickness="3 0 0 3" 

Background="#C0C0C0" 

Paddi ng="24"> 
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<Grid Name="drawi ngGrid"> 

<Polyline Name="polyli ne" 
Stroke="#404040" 
StrokeThickness="3" /> 

</Grid> 

</Border> 


〈 local:Dial x:Name="horzDial " 

Grid.Row="l" 

Grid.Column="0" 

Maximum="1800" 

Val ueChanged="OnDi alVal ueChanged"> 
<local : Dial.RenderT ransform> 

<RotateTransform /> 

</local : Dial.RenderTransform> 

〈/local : Dial > 


<Button Content="Cl ear" 

Grid.Row="l" 

Grid.Column="l" 

Hori zontalAl i gnment="Center" 

VerticalAli gnment="Center" 

Cli ck="OnCl earButtonClick" /> 

<local : Dial x:Name="vertDial " 

Grid.Row="l" 

Grid.Column="2" 

Maximum= ,, 1800" 

Val ueChanged="OnDi alValueChanged"> 

<local : Dial.RenderT ransform> 

<RotateTransform /> 

</local : Dial.RenderT ransform> 

〈 /local : Dial> 

</Grid> 

</Page> 

You’ll notice that the Maximum settings are repeated on the individual Dial controls. In the version 
of Windows 8 that I'm using, the settings in the Style didn't seem to "take." Also notice that each Dial 
control has a RototeTransform attached to it. 

The code-behind file initializes the Polyline to a point in the center. For each VolueChanged event 
from a Dial, the RotateTranform on the control is set and a new Point is added to the Polyline: 


Project: DialSketch I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

public MainPageO 
{ 

this. Ini ti alizeComponent(); 


Loaded += (sender, args)=> 

{ 

polyline.Points.Add (new Poi nt(drawingGrid.ActualWidth / 2 ， 

drawingGrid.ActualHeight / 2)) 

}； 
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void OnDialValueChanged (object sender, RangeBaseValueChangedEventArgs args) 


Dial dial = sender as Dial; 

RotateTransform rotate = dial.RenderTransform as RotateTransform ; 
rotate.Angle = args.NewValue; 

double xFraction = (horzDial.Value - horzDial.Minimum) / 

(horzDial.Maximum - horzDial.Minimum); 

double yFraction = (vertDial.Value - vertDial.Minimum) / 

(vertDial.Maximum - vertDial.Minimum); 

double x = xFraction * drawingGrid.ActualWidth; 
double y = yFraction * drawingGrid.ActualHeight; 
polyline.Points.Add (new Poi nt(x, y)); 

} 

void OnClearButtonCli ck(object sender, RoutedEventArgs args) 

{ 

polyline.Points.Clear(); 

} 

Of course, the program is still impossible to use, but it says "Hi” the best it can: 
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CHAPTER 14 

Bitmaps 


W e’ve been working with bitmap images since the early pages of this book: displaying them, 
using them for brushes, stretching them, skewing them, and rotating them. But this chapter 
is all about reaching into the inner soul of bitmaps and manipulating their pixel bits. Almost every 
program in this chapter makes use of the WriteableBitmap class, which derives from ImogeSource and 
therefore can be used as a source for Image and ImageBrush: 


Object 

DependencyObject 

ImogeSource 

BitmopSource 

Bitmaplmage 

WriteableBitmap 

From BitmopSource, WriteableBitmap inherits a SetSource method that you can use to load a bitmap 
file through an object that implements IRandomAccessStream. 

What makes WriteableBitmap different is that it defines a Pixel Buffer property that gives you 
access to the pixel bits. You can manipulate the pixels of an existing image or create an entire image 
from scratch. This chapter also discusses reading and writing various formats of image files (such as 
PNG and JPEG) based on arrays of pixel bits. 

If you're familiar with the Silverlight version of WriteableBitmap, you might be disappointed to 
learn that the Windows Runtime version does not implement the Render method that allows you 
to render any UlElement on the surface of the image. This greatly limits WriteableBitmap for several 
common purposes. 

For example, in Chapter 13, "Touch, Etc.,’’ you saw a number of finger-painting programs that 
rendered pointer input with Line, Polyline, and Path elements. You probably noticed that I provided 
no way for you to save a painting to a file. One very reasonable way to save a painting is to render 
these Line, Polyline, and Path elements on a bitmap and then save this bitmap as a file. But the 
absence of a Render method in WriteableBitmap greatly inhibits this process. 


In this chapter I’ll show you how to draw lines on a bitmap algorithmically. This allows me to 
present a FingerPaint program (without any number on the project name) that lets you store your 
artwork as a bitmap. In Chapter 15, "Going Native," 111 show you how to use Surface!mogeSource, 
which also derives from ImogeSource and can be drawn upon using DirectX drawing operations from 
C++ code. 
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It is not my policy to discuss third-party libraries in books about APIs, but if you need to draw 
complex graphics on bitmaps, you might find WriteobleBitmapEx to be useful. This is available at 
http://writeoblebitmapex.codeplex.com. 


Pixel Bits 


A bitmap image has an integral number of rows and columns. For any instance of a class that derives 
from BitmapSource, these dimensions are available from the Pixel Height and PixelWidth properties. 

Conceptually, pixel bits are stored in a two-dimensional array with the two dimensions equal to 
Pixel Height and PixelWidth. In reality, the array has just one dimension, but the big issue is the nature 
of the individual pixels themselves. This is sometimes referred to as the bitmap’s "color format” and 
could range from 1 bit per pixel (in a bitmap capable of only black and white) to 1 byte per pixel (in a 
gray-shade bitmap or a bitmap with a 256-color palette) to 3 or 4 bytes per pixel (for full-color with 
or without transparency) or even higher for more color resolution. 

However, when working with WriteobleBitmop, a uniform color format has been established. In 
every WriteobleBitmop, each pixel consists of four bytes. The total number of bytes in the bitmap’s 
pixel array is therefore 

Pixel Height * PixelWidth * 4 

The image begins with the topmost row, and each row goes from left to right. There is no row 
padding. For each pixel, the bytes are in this order: 

Blue, Green, Red, Alpha 

The bytes range from 0 to 255 just as in a Color value. The WriteobleBitmop color values are assumed 
to be in accordance with sRGB ("standard RGB") and hence compatible with the Windows Runtime 
Color value (except for Colors.Tronsparent, as 111 discuss later). 

The pixels in a WriteobleBitmop are in a premultiplied-alpha format. HI discuss what that means 
shortly. 


The order Blue, Green, Red, Alpha might seem backward from how we usually refer to these color 
bytes (and their order in the Color.FromArgb method), but it makes more sense if you consider that 
a WriteobleBitmop pixel is really a 32-bit unsigned integer with the Alpha value stored in the high 
byte and the Blue value in the low byte. That integer is stored in the bitmap in the little-endian order 
(lowest byte first) common in operating systems built around Intel microprocessors. 

Let’s construct a custom image by creating a WriteobleBitmop and filling it with pixels. Just to make 
the math easy, this WriteableBitmap will have 256 rows and 256 columns. The upper-left corner will be 
black, the upper-right corner will be blue, the lower-left corner will be red, and the lower-right corner 
will be magenta, the combination of blue and red. This is a form of gradient, but it’s not like any 
gradient available in the Windows Runtime. 
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Here’s the XAML file with an Image element ready to receive an ImogeSource derivative: 


Project: CustomGradient I File: MainPage.xaml (excerpt) 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

<Image Name="image" /> 

</Grid> 

You cannot instantiate a WriteobleBitmop in XAML because it doesn't have a parameterless 
constructor. The code-behind file creates and builds the WriteobleBitmop in a handler for the Loaded 
event. Here’s the complete file so that you can see the using directives as well. WriteableBitmap itself 
is defined in the Windows.Ul.Xoml.Medio.Imaging namespace: 


Project: CustomGradient | File: MainPage.xaml.es 
using System.10; 

using System.Runtime.InteropServices.WindowsRuntime; 

using Windows.UI.Xaml; 

using Windows.UI.Xaml .Controls; 

using Windows.UI.Xaml.Media.Imaging; 

namespace CustomGradient 

{ 

public sealed partial cl ass MainPage : Page 

{ 

public MainPageO 

{ 

this .InitializeComponent(); 

Loaded += OnMainPageLoaded; 

} 


async void OnMai nPageLoaded(object sender, RoutedEventArgs args) 

{ 

WriteableBitmap bitmap = new WriteableBi tmap(256, 256); 

byte [] pixels = new byte [4 * bitmap.PixelWidth * bitmap.Pixel Height]; 


for (int y = 0; y < bitmap.Pixel Height; y++) 
for (int x = 0; x < bitmap.Pixel Width; x++) 


int index = 4 * (y * bitmap.PixelWidth + x); 


pixels [index + 0] 
pixels [index + 1] 
pixels [index + 2] 
pixels [index + 3] 


= (byte)x; 
= 0 ; 

= (byte)y; 
= 255; 


// Blue 
// Green 
// Red 
// Alpha 


using (Stream pi xel Stream = bitmap. Pixel Buffer. AsStreamO) 

{ 

await pixel Stream.WriteAsyncCpixels, 0 ， pixels.Length); 

} 

bitmap.InvalidateO ; 
image.Source = bitmap; 
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The WriteobleBitmop constructor requires a pixel width and height. The program then allocates a 
byte array for the pixels based on those dimensions: 

byte[] pixels = new byte [4 * bitmap.PixelWidth * bitmap.Pixel Height]; 

The array size for a WriteableBitmop is always calculated like this. 

The loops for the rows and columns touch every pixel in the bitmap. An index into the pixels array 
to reference a particular pixel is calculated like this: 

int index = 4 * (y * bitmap.PixelWidth + x); 

Each pixel can then be set in the order blue, green, red, alpha. 

In this particular example, the two loops are addressing the pixels in the order in which they're 
stored in the array, so index really doesn't have to be recalculated for every pixel. It could be 
initialized at zero and then incremented like so: 


int index = 0; 

for (int y = 0; y < bitmap.Pixel Height; y++) 
for (int x = 0; x < bitmap.PixelWidth; x++) 


{ 


} 


pixels[index++] 
pixels[index++] 
pixels[index++] 
pixels[index++] 


= (byte)x; 
= 0 ; 

= (byte)y; 
= 255; 


// Blue 
// Green 
// Red 
// Alpha 


This is almost assuredly somewhat faster than the approach I’ve used, but in general it’s less versatile. 
You could also define one loop for index and then calculate x and y from that. What’s important (in 
most cases) is to access every pixel. 

After the byte array has been filled, the pixels must be transferred into the WriteableBitmop. This 
process seems puzzling on first inspection. The Pixel Buffer property defined by WriteableBitmop is 
of type I Buffer, which defines only two properties: Capacity and Length. As I discussed in Chapter 7, 
"Asynchronicity," an I Buffer object is usually an area of storage maintained within the operating sys¬ 
tem that is reference counted so that it can be deleted when no longer needed. You need to transfer 
bytes into this buffer. 


Fortunately, an extension method named As St ream is defined to treat this I Buffer as a .NET Stream 
object: 

Stream pi xel Stream = bitmap. Pi xel Buffer .AsStreamO ; 

To use this extension method, you must include a using directive for the System.Runtime 
.InteropServices.WindowsRuntime namespace. Without that using directive, IntelliSense won’t reveal 
the method’s existence. 

You can then use the normal Write method defined by Stream to write the byte array to the Stream 
object, or you can use WriteAsync as I’ve done. Because this bitmap is not very large, and because 
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the call merely transfers an array of bytes across the API, Write should be fast enough to justify doing 
the job in the user-interface thread. You can dispose of the Stream "manually" or let it be disposed of 
automatically, or you can put the Stream logic in a using statement as I’ve done: 

using (Stream pixelStream = bitmap. PixelBuffer.AsStreamO) 

{ 

await pixelStream.WriteAsync(pixels, 0, pixels.Length); 

} 

Whenever you change the pixels of a WriteobleBitmop, it’s a good idea to get into the habit of 
calling Invalidate on the bitmap: 

bitmap.Invalidate(); 

This call requests that the bitmap be redrawn. The call isn’t strictly required in this particular context, 
but it’s important in others. 

Finally, do not forget to display the final bitmap! This program simply sets it to the Source property 
of the Image element in the XAML file: 

image.Source = bitmap; 

And here’s the result: 



If you retain the Stream object and pixel array as a field for further manipulation of the bitmap — 
perhaps the image changes over time — you’ll need to precede the Wri teAsync call with a Seek call to 
set the current position back to the beginning: 

pixelStream.Seek(0, SeekOrigin. Begin); 
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But notice also that you have the option of writing only part of the byte array to the bitmap. For 
example, suppose you’ve only modified pixels corresponding to the pixel coordinate [xl,yl) up to but 
not including {x2, y2). First find the byte indices corresponding to those two coordinates: 

int indexl = 4 * (yl * bitmap.PixelWidth + xl); 
int index2 = 4 * (y2 * bitmap.PixelWidth + x2); 

Then indicate that you want to update pixels at indexl up to index2: 

pixelStream.Seek(indexl, SeekOrigin .Begin); 
pixel Stream.Write(pixels, indexl, i ndex2 - indexl); 
bitmap.Invalidate(); 

Let’s try another custom gradient. This next program I call CircularGradient and the gradient is 
based on the angle a particular pixel makes with the center of the bitmap. (The math is easier than 
you might think.) 


The XAML file defines an Ellipse with a thick outline and an ImogeBrush for the Stroke property. An 
animation rotates the Ellipse around its center: 


Project: CircularGradient | File: MainPage.xaml (excerpt) 

<Page … > 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
〈Ellipse Width="576" 

Height="576" 

StrokeThi ckness="48" 

RenderTransformOrigi n="0.5 0.5"> 

<E11ipse.Stroke> 

<ImageBrush x:Name="imageBrush" /> 

</El1ipse.Stroke> 


<E11ipse.RenderTransform> 

<RotateTransform x:Name=" rotate" /> 
</E"l 1 i pse ■ Rende 「 Transform 〉 

</El1ipse> 

</Gri d> 


<Page.Triggers> 

<EventTrigger> 

<BeginStoryboard> 

<Storyboard> 

<DoubleAnimation Storyboard.TargetName=" rotate" 

Storyboard.TargetPrope rty="Angle" 
From="0" To="360” Durati on="0 :0:3" 


</Storyboard> 
</BeginStoryboard> 
</EventTrigger> 
</Page.Triggers> 

</Page> 


RepeatBehavior="Forever" /> 
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The Loaded handler in the code-behind file is similar to the previous program. As the two loops 
march through the rows and columns of the bitmap, each pixel has a position (x, y) relative to the 
upper-left corner. The pixel in the center has the coordinate (bitmap.PixelWidth / 2, 
bitmop.PixelHeight / 2). By subtracting that center from an individual pixel and dividing by the bitmap 
width and height, the pixel coordinate is converted to values between -1/2 and 1/2, which can then 
be passed to the Math.Atan2 method to get exactly the angle we need: 


Project: CircularGradient I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

public MainPage() 

{ 

this. InitializeComponent(); 

Loaded += OnMainPageLoaded; 


async void OnMainPageLoaded (obj ect sender, RoutedEventArgs args) 

{ 

WriteableBitmap bitmap = new WriteableBi tmap(256, 256); 

byte[] pixels = new byte [4 * bitmap.PixelWidth * bitmap.Pixel Height]; 

int index = 0; 

int centerX = bitmap.PixelWidth / 2; 
int centerY = bitmap.Pixel Height / 2; 


for (int y = 0; y < bitmap.Pixel Height; y++) 
for (int x = 0; x < bitmap.PixelWidth; x++) 



double angle = 

Math . Atan2(((double)y - centerY) / bitmap.Pixel Height ， 
((double)x - centerX) / bitmap.PixelWidth); 
double fraction = angle / (2 * Math. PI); 
pixels[index++] = (byte) (fraction * 255); // Blue 

pixels[index++] =0; // Green 

pixels[index++] = (byte) (255 * (1 - fraction)); // Red 


pixels [index++] = 255; 


// Alpha 


using (Stream pi xel Stream = bitmap. Pi xel Buffer .AsStreamO) 

{ 

await pixelStream.WriteAsync(pixels, 0, pixels■Length); 

} 

bitmap.Invalidate(); 
imageBrush.ImageSource = bitmap; 



CHAPTER 14 Bitmaps 


689 


That angle is then converted to a fraction between 0 and 1 for calculating the gradient. Here’s what 
the bitmap looks like in its entirety used for an ImogeBrush set to the Fill property of a Rectangle: 



However, it looks much more interesting when it’s restricted to a circle and made to rotate. It 
seems as if the gradient itself is rotating: 



As you’ve seen, brushes in the Windows Runtime are generally stretched to the element they’re 
coloring. An ImogeBrush does that as well, so in one sense the size of the underlying bitmap doesn’t 
matter. But of course it does matter. A bitmap that is too small might not have the desired detail, and 
one that is too large is just a waste of pixels. 
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Transparency and Premultiplied Alphas 


When a bitmap is rendered on a surface such as the video display, the pixels of the bitmap are 
generally not simply transferred to the video display surface. If the bitmap supports transparency, a 
pixel must be combined with the color of the existing surface at that point based on the Alpha setting 
of that pixel. It the Alpha value is 255 (opaque), the bitmap pixel can be simply copied to the surface. 

If the Alpha value is 0 (transparent), it doesn’t need to be copied at all. If the Alpha value is 128, the 
result is the average of the bitmap pixel and the surface color prior to the rendering. 

The following formulas show this calculation for a single pixel. In reality the values A, R, G, and B 
range from 0 to 255, but the following simplified formulas assume they’ve been normalized to values 
0 through 1. The subscripts indicate the "result” of rendering a partially transparent "bitmap” pixel on 
an existing "surface ”： 
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Notice that second multiplication in each line. That’s a multiplication that involves only the bitmap 
pixel itself and not the surface. This implies that the entire process of rendering a bitmap on a surface 
can be speeded up if the R, G, and B values of the pixel have already been multiplied by the A value: 
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This convention is called "premultiplied alpha.” 

For example, suppose a non-premultiplied alpha bitmap contains a pixel with the ARGB value 
(192, 40, 60, 255). That alpha value of 192 indicates 75 percent opacity (192 divided by 255). The 
equivalent pixel with a premultiplied alpha is (192, 30, 45,192). The red, green, and blue values have 
been multiplied by 75 percent. 


When rendering a WriteobleBitmop, the operating system assumes that the pixel data has 
premultiplied alphas. For any pixel, none of the R, G, and B values should be greater than the A value. 
Nothing will "blow up” if that’s not the case, but you won’t get the colors and level of transparency 
you want. 

Let’s look at some examples. Back in Chapter 10, "Transforms,” I showed you how to flip over 
an image and make it fade out so that it looked like a reflection. However, because the Windows 
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Runtime doesn’t support an opacity mask , 丨 had to fade out the reflected image by covering it with a 
partially transparent rectangle. 

In the ReflectedAlphalmage project I take a different approach. The XAML file has two Image 
elements occupying the same top cell of a two-row Grid. The second Image element has a 
RenderTransformOrigin and ScoleTransform to flip it around its bottom edge, but no bitmap has been 
specified: 


Project: ReflectedAlphalmage I File: MainPage.xaml (excerpt) 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Grid.RowDefinitions> 

〈RowDefinition Height:"*'’ /> 

〈RowDefinition Height="*" /> 

</Grid.RowDefiniti ons> 


<Image Sou rce="http: //www.char!espetzold.com/pw6/PetzoldJersey.jpg" 
HorizontalAli gnment="Center" /> 

<Image Name=" ref1ectedlmage" 

RenderTransformOrigi n="0 1" 

HorizontalAli gnment="Center"> 

<Image.RenderTransform> 

<ScaleTransform ScaleY="-l" /> 

</Image.RenderTransform> 

</Image> 

</Crid> 


The same bitmap referenced by the first Image element must be loaded independently in the 
code-behind file. (You might wonder if it's possible to obtain a WriteableBitmap based on the object 
that’s set to the Source property of the first Image object. But that’s an object of type BitmopSource, 
and you can't create a WriteableBitmap from a BitmopSource.) If it's not necessary to modify that 
downloaded bitmap, the code in the constructor might look something like this: 


Loaded += async (sender, args)=> 

{ 

Uri uri = new Uri ("http : //www.charlespetzold.com/pw6/PetzoldDersey.jpg ")； 
RandomAccessStreamReference streamRef = RandomAccessStreamReference.CreateFromUri (uri); 
IRandomAccessStreamWithContentType fi1eStream = await streamRef.OpenReadAsyncO; 

WriteableBitmap bitmap = new WriteableBitmap (1, 1); 

bitmap.SetSource(fi1eStream); 
reflectedlmage.Source = bitmap; 


It’s necessary to put this code in the Loaded handler because some asynchronous processing is 
involved. Notice that a WriteableBitmap can be created with essentially an "unknown" size if the data 
is coming from the SetSource method. When the WriteableBitmap reads that JPEG stream, it can 
figure out what the actual pixel dimensions are. 

However, when that fileStream object is passed to the SetSource method of WriteableBitmap and 
when that WriteableBitmap is set to the Source property of the Image element, the bitmap has not 
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yet been downloaded. That downloading occurs asynchronously within WriteableBitmop. This means 
that you can’t yet start modifying the pixels because the pixels have not yet arrived! It would be nice 
if WriteableBitmap defined an event like Bitmoplmoge does that indicates when SetSource completes 
loading the bitmap file, but that’s not the case. Nor does the ImogeOpened event of the Image 
element provide this information for a WriteobleBitmap. 

So, we’re left with the job of loading in the bitmap file ourselves and then making the 
modifications to it. Some of the code I'm going to show you can be simplified with other classes 
covered later in this chapter, but let’s look at how it’s done without those classes. Here’s the process: 

Project: ReflectedAlphalmage I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

public MainPageO 

{ 

this .Ini ti alizeComponent(); 

Loaded += OnMainPageLoaded; 

} 

async void OnMainPageLoaded (object sender, RoutedEventArgs args) 

{ 

Uri uri = new Uri ("http : //www.charlespetzold.com/pw6/PetzoldDersey.jpg ")； 

RandomAccessStreamReference streamRef = RandomAccessStreamReference.CreateFromUri (uri); 


// Create a buffer for reading the stream 
Windows.Storage.Streams. Buffer buffer = null; 

// Read the entire file 

using (IRandomAccessStreamWithContentType fi1eStream = await streamRef.OpenReadAsyncO) 

{ 

buffer = new Windows.Storage.Streams. Buffer((ui nt)fi 1eStream.Size); 

await fi1eStream.ReadAsync(buffer, (uint) fi1eStream.Size, InputStreamOptions .None); 

} 

// Create WriteableBitmap with unknown size 

WriteableBitmap bitmap = new WriteableBi tmap(l, 1); 

// Create a memory stream for transferring the data 

using (InMemoryRandomAccessStream memoryStream = new InMemoryRandomAccessStreamO) 

{ 

await memoryStream.WriteAsync(buffer); 
memoryStream.Seek(O); 

// Use the memory stream as the Bitmap source 
bitmap.SetSource(memoryStream); 

} 
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// Now get the pixels from the bitmap 

byte [] pixels = new byte [4 * bitmap.PixelWidth * bitmap.Pixel Height]; 
int index = 0; 


using (Stream pixel Stream = bitmap. Pixel Buffer .AsStreamO) 

{ 

await pixelStream.ReadAsync(pixels, 0, pixels■Length); 

// Apply opacity to the pixels 

for (int y = 0; y < bitmap.PixelHeight; y++) 

{ 

double opacity = (double)y / bitmap.PixelHeight; 

for (int x = 0; x < bitmap.PixelWidth; x++) 
for (int i =0; i <4; i++) 

{ 

pixels[index] = (byte) (opacity * pixels[index]); 
index++; 

} 

} 

// Put the pixels back in the bitmap 

pixelStream.Seek(0, SeekOrigin. Begin); 

await pixelStream.WriteAsync(pixels, 0, pixels.Length); 

} 

bitmap.Invalidate(); 

reflectedlmage.Source = bitmap; 



The Buffer class needs a fully qualified name that includes the Windows.Storage.Streams namespace 
because the System namespace also includes a class named Buffer. 


One objective here is to pass an object of type IRondomAccessStreom to the SetSource method of 
the Wri tea bl eBitmop. However, immediately after this is done, we want to start working with the pixels 
of the resultant bitmap. This can’t happen unless the file has been fully read. 

That’s the rationale for creating a Buffer object for reading the fileStreom object, and then using 
that same Buffer object to write the contents to an InMemoryRandomAccessStreom. As its name sug¬ 
gests, the InMemoryRondomAccessStream class implements the IRandomAccessStream interface so 
that it can be passed to the SetSource method of WriteobleBitmop. (But notice that the stream posi¬ 
tion must first be set back to zero.) 

It’s important to realize that we’re working with two very different chunks of data here. The 
fileStreom references the PNG file, which in this case is 82,824 bytes of compressed image data. The 
InMemoryRondomAccessStream is that same chunk of data. Once that stream has been passed to 
the SetSource method of WriteobleBitmop, it is decoded into rows and columns of pixels. The pixels 
array is 512,000 bytes in size, and the pixel Stream object references those decompressed pixels. The 
pixelStream object is first used to read the pixels into the pixels array and then to write them back out 
into the bitmap. 
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Between those two calls is the actual application of the gradient opacity. If the pixels of a 
WriteableBitmop were not assumed by the Windows Runtime to have a premultiplied alpha format, 
only the Alpha byte would need to be modified. The premulitiplied format requires the color bytes to 
be multiplied as well. Here’s the result: 



If you want to see what happens if you adjust only the Alpha byte, substitute the following code 
for the inner loop: 

for (int i =0; i <4; i++) 

{ 

if (i == 3) 

pixels[index] = (byte) (opacity * pixels[index]); 
index++; 

} 

You get the transparency you want, but only if the background is white. If the background is black, 
there’s no transparency at all! Look at the formulas and it all becomes clear. 

Suppose you wanted to alter the CircularGradient project so that the gradient is from a solid color 
to complete transparency. Here’s the altered code to set the four bytes: 


pixels[index++] 
pixels[index++] 
pixels[index++] 
pixels[index++] 


= (byte) (fraction * 
= 0 ; 

= 0 ; 

= (byte) (fraction * 


255); 

// Blue 


// Green 


// Red 
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The Blue component and the Alpha component get the same setting. With a non-premultiplied Alpha 
format, the Blue component would always be 255. Here’s the result: 



A Radial Gradient Brush 


One of the many mysteriously missing pieces of the Windows Runtime is RodiolGrodientBrush, which 
is generally used to color a circle with a gradient from a point within that circle to the perimeter. One 
common use of RadialGradientBrush \s to turn a circle into a three-dimensionalish "ball” that looks as 
if some light is reflecting off an area near the upper-left corner. 

I began writing my RadialGrodientBrushSimulotor class with an idea about animating 
the GradientOrigin property of this class in a XAML file. For that reason, I made 
RodiolGracJientBrushSimulator a FromeworkElement derivative even though it doesn’t display 
anything on its own. By making it derive from FromeworkElement I could more easily instantiate the 
class in XAML. And because I was thinking about animations and bindings, I defined all the properties 
as dependency properties. Here’s the part of the class containing little more than the dependency 
property overhead: 


Project: RadialGradientBrushDemo | File: RadialGradientBrushSimulator.es (excerpt) 

public class RadialGradientBrushSimulator : FrameworkElement 


static readonly DependencyProperty gradientOriginProperty = 

DependencyProperty .Regi ster("GradientOrigin" , 
typeof (Point) , 

typeof (Radi alGradientBrushSimul ator) , 

new PropertyMetadata(new Point (0.5 ， 0.5), OnPropertyChanged)); 
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static readonly DependencyProperty innerColorProperty = 
DependencyProperty . Regi ster(''InnerColor '' ， 
typeof (Color) , 

typeof (Radi alGradientBrushSi mul ator) , 

new PropertyMetadataCColors .White, OnPropertyChanged)); 

static readonly DependencyProperty outerColorProperty = 
DependencyProperty .Regi ster("OuterColor" , 
typeof (Color) , 

typeof (Radi alGradientBrushSimul ator) , 

new PropertyMetadataCColors .B1ack, OnPropertyChanged)); 

static readonly DependencyProperty clipToEl1ipseProperty = 
DependencyProperty .Regi ster("Cl ipToEl1ipse" , 
typeof(bool ), 

typeof (Radi alGradientBrushSimul ator) , 

new PropertyMetadata(fal se , OnPropertyChanged)); 

public static DependencyProperty imageSourceProperty = 
DependencyProperty .Regi sterC'ImageSource " ， 
typeof (ImageSource ) ， 
typeof (Radi alGradientBrushSimul ator ) ， 
new PropertyMetadata(nul 1)) ; 

public RadialGradientBrushSimulator() 

{ 

SizeChanged += OnSizeChanged; 

} 

public static DependencyProperty GradientOriginProperty 

{ 

get { return gradientOriginProperty; } 

} 

public static DependencyProperty InnerColorProperty 

{ 

get { return innerColorProperty; } 

} 

public static DependencyProperty OuterColorProperty 

{ 

get { return outerColorProperty; } 

} 

public static DependencyProperty ClipToEl1ipseProperty 

{ 

get { return clipToEl1ipseProperty; } 

} 

public static DependencyProperty ImageSourceProperty 

{ 

get { return imageSourceProperty; } 

} 

public Point GradientOrigin 


set { SetValue(GradientOriginProperty, value); } 
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} 


get { return (Poi nt)GetValue(GradientOriginProperty); } 


public Color InnerColor 
{ 

set { SetValue(InnerColorProperty, value); } 

get { return (Color)GetValue(InnerColorProperty); } 

} 

public Color OuterColor 
{ 

set { SetValue(OuterColorProperty, value); } 

get { return (Col or)GetValue(OuterColorProperty); } 

} 

public bool ClipToEllipse 
{ 

set { SetValue(ClipToEl1ipseProperty, value); } 
get { return (bool )GetValue(ClipToEl1ipseProperty); } 

} 

public ImageSource ImageSource 
{ 

private set { SetValue(ImageSourceProperty, value); } 
get { return (ImagGSource)GetValue(ImageSourceProperty); } 

} 

void OnSizeChanged (ob ject sender, SizeChangedEventArgs args) 

{ 

thi s . Ref reshBi tmapO ; 

} 

static void OnPropertyChanged(DependencyObject obj, DependencyPropertyChangedEventArgs args) 
{ 

(obj as RadialGradientBrushSimul ator) .RefreshBitmap(); 

} 

} 

In the RefreshBitmap method shown later, the class uses the GrodientOrigin, InnerColor, OuterColor, 
and ClipToEllipse properties (as well as the ActualWidth and ActuolHeight of the element) to create a 
WriteableBitmap that the class exposes through the ImageSource property, allowing another element 
in the XAML file to reference that through a binding to the ImageSource property of an ImageBrush. 

It was then that I discovered that the algorithm to make an image of a radial gradient brush was 
not exactly trivial. Conceptually, you’re dealing with an ellipse, although you can use the bitmap to 
color a rectangle or anything else. The color at the boundary of the ellipse is the OuterColor property. 
The GradientOrigin property of type Point is in relative coordinates. For example, a value of (0.5, 0.5) 
would set the GradientOrigin to the center of the ellipse. The color at the GradientOrigin is the prop¬ 
erty InnerColor. 

For any point (x, y) within the bitmap, the algorithm needs to find an interpolation factor to cal¬ 
culate a color between InnerColor and OuterColor. This interpolation factor is based on a straight line 
from the GradientOrigin through the point [x, y) to the circumference of the ellipse. Where the point 
[x, y) divides that line determines the value of the interpolation factor. 


698 PART Specialties 


For best performance I wanted to avoid trigonometry. Instead, my strategy involved finding the 
intersection of the circumference of the ellipse with the line from the GrodientOrigin to [x, y). This 
involved solving a quadratic equation for every point in the bitmap. 

Here's the RefreshBitmap method: 

Project: RadialGradientBrushDemo I File: RadialGradientBrushSimulator.es (excerpt) 

public class RadialGradientBrushSimulator : FrameworkElement 

{ 

WriteableBitmap bitmap; 
byte[] pixels; 

Stream pixel Stream; 


void RefreshBitmap() 

{ 

if (thi s .ActualWidth == 0 || this .ActualHeight == 0) 

{ 

this .ImageSource = null; 
bitmap = null ; 
pixels = null ; 
pixel Stream = null ; 
return ; 

} 


if (bitmap == null || (i nt)this .ActualWidth != bitmap.PixelWidth || 

(i nt)this .ActualHeight != bitmap.PixelHeight) 

{ 

bitmap = new WriteableBitmap( (i nt)this .ActualWidth, (i nt)this .ActualHeight); 
this .ImageSource = bitmap; 

pixels = new byte [4 * bitmap.PixelWidth * bitmap.PixelHeight]; 
pixel Stream = bitmap.PixelBuffer.AsStreamC); 

} 

else 


{ 

for (i nt i =0; i < pixels.Length; i++) 
pixels [i] =0; 

} 


double xOrigin = 2 * this .GradientOrigin.X - 1; 
double yOrigin = 2 * this .GradientOrigin.Y - 1; 

byte aOutsideCircle = 0; 
byte rOutsideCircle =0; 
byte gOutsideCircle = 0; 
byte bOutsideCircle = 0; 


if (! this .ClipToEl1ipse) 



} 


double opacity = this .OuterColor.A / 255.0; 
aOutsideCircle = this .OuterColor.A; 


rOutsideCircle = (byte) (opacity * this .OuterColor.R); 
gOutsi deCircle = (byte) (opaci ty * this.OuterColor.G) ; 
gOutsideCircle = (byte) (opacity * this .OuterColor.B); 


int index = 0; 
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for (i nt yPixel = 0; yPixel < bitmap.Pixel Height; yPixel++) 

{ 

// Calculate y relative to unit circle 

double y = 2.0 * yPixel / bitmap.PixelHeight - 1; 

for (i nt xPixel = 0; xPixel < bitmap.PixelWidth; xPixel++) 

{ 

// Calculate x relative to unit circle 

double x = 2.0 * xPixel / bitmap.PixelWidth - 1; 


// Check if point is within circle 
if (x * x + y * y <= 1) 

{ 

// relative length from gradient origin to point 
double lengthl = 0; 

// relative length from point to unit circle 
// (lengthl + length2 = 1) 
double 1ength2 = 0; 

if (x == xOrigin && y == yOrigin) 

{ 

length2 = 1; 

} 

el se 

{ 

// Remember: xCircle 八 2 + yCircle 八 2 = 1 
double xCircle = 0 ， yCircle = 0; 

if (x == xOrigin) 

{ 

xCircle = x; 

yCircle = (y < yOrigin ? -1 : 1) * Math.Sqrt(l - x * x); 

} 

else if (y == yOrigin) 

{ 

xCircle = (x < xOrigin ? -1 : 1) * Math.Sqrt(l - y * y); 
yCircle = y; 

} 

el se 

{ 

// Express line from origin to point as y = mx + k 
double m = (yOrigin - y) / (xOrigin - x); 
double k = y - m * x; 

// Now substitute (mx + k) for y into xA2 + yA2 = 1 

// xA2 + (mx + k) 八 2 = 1 

// xA2 + (mx) 八 2 + 2mxk + k 八 2 -1=0 

// (1 + mA2)xA2 + (2mk)x + (kA2 - 1) = 0 is quadratic equation 
double a = 1 + m * m; 

double b = 2 * m * k; 

double c = k * k - 1; 
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// Now solve for x 

double sqrtTerm = Math .Sqrt(b * b - 4 * a * c); 
double xl = (-b + sqrtTerm) / (2 * a); 


double x2 = (-b - sqrtTerm) / (2 * a); 

if (x < xOrigin) 

xCircle = Math .Min(xl, x2); 

el se 

xCircle = Math .Max(xl, x2); 
yCircle = m * xCircle + k; 

} 

// Length from oh gin to point 
lengthl = Math .Sqrt(Math.Pow(x - xOrigin, 2) + 
Math.PowCy - yOrigin, 2)); 

// Length from point to circle 
length2 = Math .Sqrt(Math.Pow(x - xCircle, 2) + 
Math.PowCy - yCircle, 2)); 


// Normalize those lengths 
double total = lengthl + length2; 
lengthl /= total; 
length2 /= total; 


// Interpol ate color 

double alpha = 1 ength2 * this .InnerColor.A + lengthl * this .OuterColor.A; 
double red= alpha * (length2 * this. InnerColor.R + 

lengthl * this .OuterColor.R) / 255; 
double green = alpha * (1ength2 * this. InnerColor.G + 

lengthl * this. OuterColor.G) / 255; 
double blue = alpha * (1ength2 * this .InnerColor.B + 

lengthl * this .OuterColor.B) / 255; 


// Store in array 
pixels[index++]= 
pixels[index++]= 
pixels[index++]= 
pixels[index++]= 


(byte)bl ue; 
(byte)green ; 
(byte) red; 
(byte)al pha; 


else 




pixels[index++]= 
pixels[index++]= 
pixels[index++]= 
pixels[index++]= 


bOutsideCircle 
gOutsideCircle 
rOutsideCircle 
aOutsideCircle 


pixelStream.Seek(0, SeekOrigin .Begin); 
pixel Stream.Write(pixels ， 0 ， pixels.Length); 
bitmap.Invalidate(); 


With an eye toward making this animatable, the array of pixels and the Stream object used to transfer 
the pixels into the bitmap are both saved as fields. No allocations from the heap are required in the 
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RefreshBitmop method unless the WriteobleBitmop needs to be re-created because the size of the 
element has changed. 


As it turned out, however, animation performance was very poor, even with rather small dimen¬ 
sions. But if you avoid animating the gradient itself, you can surely animate an object colored with this 
bitmap. The MainPage.xaml file instantiates both a RodialGrodientBrushSimulotor and an Ellipse with a 
binding to the simulator, as well as a couple animations: 


Project: RadialGradientBrushDemo | File: MainPage.xaml (excerpt) 

<Page … > 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
cCanvas Si zeChanged="OnCanvasSi zeChanged" 

Margin="0 0 96 96"> 

<Grid Name="bal IContainer" 

Width="96" 

Height="96"> 

〈Ellipse Name="elli pse"> 

<Ellipse.Fill> 

<ImageBrush ImageSource="{Bi nding El ementName=brushSi mulator, 

Path=ImageSource}" /> 

</El1ipse.Fill> 

</El1ipse> 

<local : RadialGradientBrushSimulator x : Name="brushSimul ator" 

InnerColor="Whi te" 
OuterColor="Red" 

GradientOrigi n="0. 3 0.3" /> 

</Gri d> 

</Canvas> 

</Gri d> 

<Page.Triggers> 

<EventTrigger> 

<BeginStoryboard> 

<Storyboard> 

<DoubleAnimation x : Name="l eftAnima" 

Storyboard .TargetName="ballContai ner" 

Storyboard.TargetProperty=" (Canvas.Left)" 
From="0" Durati on="0 :0:2.51" 

AutoReverse="True" 

RepeatBehavior=" Forever" /> 

<DoubleAnimation x : Name="ri ghtAnima" 

Storyboard .TargetName="bal IContainer" 

Storyboard.TargetProperty=" (Canvas.Top)" 

From="0" Durati on="0: 0:1.01" 

AutoReverse="T rue" 

RepeatBehavior=" Forever" /> 

</Storyboard> 

</BeginStoryboard> 

</EventTrigger> 

</Page.Triggers> 

</Page> 
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Notice how I’ve put the Ellipse and the RodialGrodientBrushSimulator in the same 96-pixel-square 
Grid so that both elements have the same size and the simulator generates a bitmap of exactly the 
same size as the Ellipse it’s used to color. The code-behind file simply adjusts the To values on the 
animations based on the size of the Convos: 


Project: RadialGradientBrushDemo I File: MainPage.xaml.es (excerpt) 

void OnCanvasSizeChanged (object sender, SizeChangedEventArgs args) 
{ 

// Canvas.Left animation 
leftAnima.To = args.NewSize.Width; 

// Canvas.Top animation 
rightAnima.To = args.NewSize.Height; 

} 


The simulated light reflection makes the Ellipse come one step closer to looking like something 
that might be found in the real world: 



Loading and Saving Image Files 

As you’ve seen, you can give the SetSource method of WriteableBitmop a stream referencing a PNG 
file, and it will graciously decode that compressed file and convert it into an array of rows and col¬ 
umns. You can get closer to this process with classes in the Windows.Graphics.Imaging namespace. 
You can load a bitmap file as an array of pixel bits, and you can also go the other way: You can save 
an array of pixel bits from a WriteableBitmop that's been created in your program to a file in one of 
several popular image formats. 

Bitmap file formats are generally differentiated by the type of compression they use (including 
none at all) and of course unique data structures, headers, and techniques for storing the compressed 
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data. Code that knows how to read a specific file format and convert it into an array of pixels is known 
as a decoder. Decoders allow you to load image files into an application. The BitmopDecoder class in 
the Windows.Graphics.Imaging namespace supports the formats in the following table. 


File Format 

MIME Types 

Filename Extensions 

Windows Bitmap 

image/bmp 

.bmp 

■dib 

•rle 

Windows Icon 

image/ico 

•ico 


image/x-icon 

.icon 

GIF files 

image/gif 

•gif 

JPEG 

image/jpeg 

•jpeg 


image/jpe 

.jpe 


image/jpg 

•jpg 

jfif 

•exif 

PNG 

image/png 

• png 

TIFF 

image/tiff 

.tiff 


image/tif 

.tif 

WM Photo 

image/vnd. ms-photo 

•wdp 

•jxr 


The BitmopDecoder class will determine what type of file it’s been asked to load and will raise an 
exception if it can’t figure it out. 

Code that creates a file of a particular format from an array of pixel bits is called an encoder, and in 
the Windows Runtime it’s the BitmopEncoder class. Using an encoder is a little different from using a 
decoder. A decoder can determine what type of file it’s being requested to load, but an encoder can’t 
read your mind and determine the file format for a save. It must be told. The BitmopEncoder class 
supports the same formats as the BitmopDecoder except for the Windows Icon file. 

Sometimes encoders and decoders are referred to collectively as codecs, which conveniently stands 
for either "coder/decoder" or "compressor/decompressor." 

The seven file formats shown in the preceding table are identified by global unique IDs (objects of 
type Guid) defined as static properties in the BitmopEncoder and BitmopDecoder classes, but you re¬ 
ally don’t need to hard-code these IDs in your program or, indeed, include much specific information 
at all. 

The ImageFilelO program demonstrates how to use the FileOpenPicker and a BitmopDecoder to 
load a bitmap file into an application and how to use the FileSovePicker and a BitmopEncoder to select 
a file format and save a bitmap file from an application. In between, it has a couple application bar 
buttons to rotate the image by 90 degrees. Because this program uses the file pickers for obtaining 
StorogeFile objects, it does not require any special permission for accessing the user's files. 
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The XAML file defines an Image element, a TextBlock for displaying some information about the 
loaded bitmap, and an AppBor: 


Project: ImageFilelO I File: MainPage.xaml (excerpt) 

<Page … > 

<Grid Background="Gray"> 

<Grid.RowDefiniti ons> 

<RowDefinition Hei ght="Auto" /> 
〈RowDefinition Height="*" /> 

</Grid.RowDefi ni ti ons> 

〈TextBlock Name="txtbl k" 

Grid■ Row="0" 

HorizontalAli gnment="Center" 
FontSize="18" /> 

<Image Name="image" 

Grid.Row="l" /> 

</Grid> 


<Page.BottomAppBar> 

<AppBar IsOpen="True"> 

<Gri d> 

<StackPanel Orientati on="Hori zontal" 

HorizontalAli gnment="Left"> 

<Button Name="rotateLeft Button" 

IsEnabl ed="Fal se" 

Style="{StaticResource AppBarButtonStyl e} 
Content="&#x21B6 ;" 

AutomationProperties. Name="Rotate Left" 

Cli ck="OnRotateLeftAppBarButtonClick" /> 

<Button Name="rotateRi ghtButton" 

IsEnabl ed="Fal se" 

Style="{StaticResource AppBarButtonStyl e} 
Content="&#x21B7 ;" 

AutomationProperties. Name="Rotate Right" 
Cli ck="OnRotateRi ghtAppBarButtonClick" /> 
</StackPanel > 


<StackPanel Orientati on="Hori zontal" 

HorizontalAli gnment="Ri ght"> 

<Button Style="{StaticResource OpenFileAppBarButtonStyle}" 
Cli ck="OnOpenAppBarButtonClick" /> 

<Button Name="saveAsButton" 

IsEnabl ed="Fal se" 

Style="{StaticResource SaveLocalAppBarButtonStyl e} 
AutomationProperties. Name="Save As" 

Cli ck="OnSaveAsAppBarButtonClick" /> 

</StackPanel > 
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</Grid> 

</AppBar> 

</Page.BottomAppBar> 

</Page> 

Notice that the AppBar has its IsOpen property initialized to true. The program can’t do anything until 
a file is loaded. All the other buttons on the AppBar are disabled. 

To keep the program relatively simple, it doesn’t retain a lot of information. Any bitmap the 
program loads from the disk is retained only as the Source property of the Image element. The only 
fields defined in the code-behind file serve solely to store bitmap resolution information, and that’s 
not crucial: 

Project: ImageFilelO I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

double dpiX, dpiY; 

public MainPageC) 

{ 

this .InitializeComponent(); 



When the user clicks the Open button on the AppBar, the program creates a FileOpenPicker 
initialized to display the files in the Pictures folder: 


Project: ImageFilelO I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 


async void OnOpenAppBarButtonCli ck(object sender, RoutedEventArgs args) 

{ 

// Create FileOpenPicker 

FileOpenPicker picker = new Fi1eOpenPicker() ; 

picker.SuggestedStartLocation = PickerLocationld. PicturesLibrary; 

// Initialize with filename extensions 

IReadOnlyList<BitmapCodecInformation> codeclnfos = 

BitmapDecoder .GetDecoderlnformationEnumerator(); 


foreach (BitmapCodecInformation codeclnfo in codeclnfos) 
foreach (string extension in codeclnfo.Fi1eExtensions) 
picker.Fi1eTypeFiIter.Add(extension); 

// Get the selected file 

StorageFi1e storageFi1e = await picker.PickSingleFileAsync(); 
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if (storageFi1e 
return ; 


null) 


} 

The static BitmopDecoder.GetDecoderlnformotionEnumerator is of enormous assistance here. It 
returns a collection of seven BitmapCodecInformation objects corresponding to the seven file formats 
in the table shown a few pages ago. Each of these contains a collection of MIME types and a collec¬ 
tion of filename extensions. (This is what I used to obtain the information shown in that table.) Those 
filename extensions can go right into the FileOpenPicker object, and the FileOpenPicker then displays 
all the files with those extensions. 

If the PickSingleFileAsync call returns a non-null Storage File object, the next step is to create a 
BitmapDecoder from that file: 

Project: ImageFilelO I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

async void OnOpenAppBarButtonCli ck(object sender, RoutedEventArgs args) 

{ 

// Open the stream and create a decoder 
BitmapDecoder decoder = null; 

using (IRandomAccessStreamWithContentType stream = await storageFile.OpenReadAsyncO) 

{ 

string exception = null; 


try 


decoder = await BitmapDecoder. CreateAsync(stream); 


catch (Exception exc) 

{ 

exception = exc.Message; 

} 


if (exception != null) 

{ 

MessageDialog msgdlg = 

new MessageDi alog("That particular image file could not be loaded. 

"The system reports an error of: " + exception); 
await msgdlg.ShowAsyncO ; 
return ; 
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BitmapDecoder.CreateAsync method could raise an exception if it is given a non-image file or 
something else it can’t handle. 

As you might know, a GIF file can contain multiple images that in sequence play a rudimentary 
animation. These individual images are known as frames, and they are supported by the Windows 
Runtime. After you create a BitmopDecoder object, the next step is generally to start extracting 
frames. However, if you don't want to bother with multiframe GIF files — and I don't blame you if 
you don’t! — you can simply extract the first frame and call it a day. This is what I’ve done in the next 
section of the code: 


Project: ImageFilelO I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

async void OnOpenAppBarButtonCli ck(object sender, RoutedEventArgs args) 

{ 

// Get the first frame 

BitmapFrame bitmapFrame = await decoder.GetFrameAsync(O); 

// Set information title 

txtblk.Text = String. Format ("{0} : {1} x {2} {3} {4} x {5} DPI" , 

storageFile.Name, 

bitmapFrame.PixelWidth, bitmapFrame.PixelHeight, 
bitmapFrame.BitmapPixelFormat, 
bitmapFrame.DpiX, bitmapFrame.DpiY); 

// Save the resolution 
dpiX = bitmapFrame.Dpi X; 
dpiY = bitmapFrame.DpiY; 

// Get the pixels 
PixelDataProvider dataProvider = 

await bitmapFrame.GetPixelDataAsync(Bi tmapPixelFormat. Bgra8, 

BitmapAlphaMode .Premultiplied, 

new BitmapTransformO , 

ExifOri entati onMode. RespectExifOrientation ， 
ColorManagementMode .ColorManageToSRgb); 

byte[] pixels = dataProvider.DetachPixelData(); 



The method displays information about the first frame in the TextBlock at the top of the page and 
saves the resolution settings as fields. 
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The BitmapPixelFormat and BitmapAlphoMode properties of the BitmapFrame contain important 
information about the format of the pixels. BitmapPixelFormat is an enumeration with the members 
Rgbal6 (red, green, blue, and alpha 16-bit values), Rgba8 (red, green, blue, and alpha 8-bit values), or 
Bgro8 (blue, green, red, and alpha 8-bit values), the last of which is compatible with the format associ¬ 
ated with WriteobleBitmop. Pixel data from the file is always converted into one of these formats. The 
BitmapAlphoMode property can indicate Ignore, Straight, or Premultiplied. 

You can obtain a byte array of pixels in the pixel format of the frame simply by calling the 
G e tPixe ID a to A syn c method with no arguments. However, if you want to use the bitmap data to create 
a WriteobleBitmop, you should call the longer version of GetPixelDataAsync as shown here to specify 
the format compatible with WriteableBitmop. 

After G e t Pixel D o to A syn c obtains an array of bytes in the same format supported by 
WriteobleBitmop, the code to create and display the bitmap is similar to what you’ve seen before: 

Project: ImageFilelO | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 
{ 

async void OnOpenAppBarButtonCli ck(object sender, RoutedEventArgs args) 

{ 

// Create WriteableBitmap and set the pixels 

WriteableBitmap bitmap = new WriteableBi tmap((i nt)bi tmapFrame.PixelWidth, 

(int)bi tmapFrame.Pixel Height); 

using (Stream pi xel Stream = bitmap. Pixel Buffer. AsStreamO) 

{ 

await pixelStream.WriteAsyncCpixels, 0 ， pixels.Length); 

} 

// Invalidate the WriteableBitmap and set as Image source 
bitmap.Invalidate(); 
image.Source = bitmap; 

} 

// Enable the other buttons 
saveAsButton.IsEnabled = true; 
rotateLeftButton.IsEnabled = true; 
rotateRightButton.IsEnabled = true ; 



That concludes the processing of the Open button. In summary, the FileOpenPicker returns 
a StorageFile object, this is opened and a stream is passed to BitmopDecoder.CreateAsync. The 
BitmapDecoder object exposes the images as BitmapFrame objects, and the GetPixelDatoAsync 
method obtains an array of bytes that can be used to create a WriteobleBitmop. 
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Here’s the program displaying a bitmap I used in Chapter 13, "Touch, Etc.": 



The Save As button on the application bar executes the OnSaveAsAppBorButtonClick method, 
which begins by creating a FileSovePicker object. The BitmapEncoder 

.GetEncoderlnformationEnumerotor provides information about the file formats supported by 
the BitmapEncoder class, but this information is used in a somewhat different way than with the 
FileOpenPicker. 

The FileSovePicker wants a list of file types accompanied by one or more filename extensions 
for each type. The FriendlyNome property of the BitmapCodecInformation object is unfortunately a 
string like "JPEG Encoder,” so I use the Split method of String to extract just the first word (for example 
"JPEG"), and I combine that with the accumulated filename extensions. The code also constructs a 
dictionary of the supported MIME types and the Guid objects associated with those types: 


Project: ImageFilelO I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 


async void OnSaveAsAppBarButtonCli ck(object sender, RoutedEventArgs args) 

{ 

Fi1eSavePicker picker = new Fi1eSavePi cker() ; 

picker.SuggestedStartLocation = PickerLocationld. PicturesLibrary; 

// Get the encoder information 

Dicti onary<stri ng , Gui d> imageTypes = new Dicti onary<stri ng , Gui d>(); 
IReadOnlyLi st<Bi tmapCodecInformati on> codeclnfos = 

BitmapEncoder .GetEncoderlnformationEnumerator(); 


foreach (Bi tmapCodecInformation codeclnfo in codeclnfos) 

{ 

Li st<stri ng> extensions = new Li st<stri ng>() ; 
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foreach (string extension in codeclnfo.Fi1eExtensions) 
extensions.Add(extension); 

string fi1etype = codeclnfo.FriendlyName.Split(' ' ) [0]; 
picker.Fi1eTypeChoices.Add(fi 1etype, extensions); 

foreach (string mimeType in codeclnfo.MimeTypes) 
imageTypes.Add(mimeType, codeclnfo.Codecld); 

} 


// Get a selected StorageFi1e 

StorageFi 1 e StorageFi1e = await picker.PickSaveFileAsyncC); 

if (StorageFi1e == null) 
return ; 


When the FileSovePicker displays itself, the user can select one of the file types from the popup 
box: 


Files 

v Pictures 


Go up 

Sort by name v 


Camera Roll 



Screenshots 



Windows Simulator 




BMP (.bmp;.dib;.rie) 



GIF (.gif) 

JPEG (.jpeg;.jpe;.jpg;.jfift.exif) 
PNG (.png) 

TIFF 

WMPhoto (.wdp;.jxr) 



The Storage File object returned from the FileSavePicker has a Conte ntType field, which is a MIME 
type string that identifies the file type that the user chose from that popup. The program can use this 
with its own dictionary to obtain the Guid object associated with that type: 


Project: ImageFilelO | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 


async void OnSaveAsAppBarButtonCli ck(object sender, RoutedEventArgs args) 
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// Open the StorageFi1e 

using (IRandomAccessStream fi1eStream = 

await StorageFi1e.OpenAsync(Fi 1eAccessMode. ReadWrite)) 

{ 

// Create an encoder 

Guid codecld = imageTypes[StorageFi1e.ContentType]; 

BitmapEncoder encoder = await BitmapEncoder .CreateAsync(codecld, fi1eStream); 

// Get the pixels from the existing WriteableBitmap 
WriteableBitmap bitmap = image.Source as WriteableBitmap; 

byte[] pixels = new byte [4 * bitmap.PixelWidth * bitmap.PixelHeight]; 

using (Stream pixel St ream = bitmap. PixelBuffer.AsStreamO) 

{ 

await pixel Stream.ReadAsync(pixels, 0 ， pixels.Length); 

} 

// Write those pixels to the first frame 

encoder.SetPixel Data(Bi tmapPixelFormat. Bgra8, BitmapAlphaMode. Premultiplied ， 

(ui nt)bi tmap.PixelWidth ， (ui nt) bitmap.PixelHeight ， 
dpiX, dpiY, pixels); 

await encoder. FlushAsyncO ; 

} 

} 

} 

With the help of that Guid, the static BitmopEncoder.CreateAsync method returns a BitmopEncoder 
object. That object has a SetPixelData method that can be used to transfer a byte array into the first 
frame of the new image file. The Save As operation is complete. 

The remainder of the program supports rotating the images by 90 degrees. This feature is actually 
available in the BitmopEncoder class. The class defines a Transform property that you can use to scale, 
flip, crop, or rotate the image in 90-degree increments as it’s being saved. However, if you want to see 
the transformed image, you’ll have to perform the logic yourself. 

Here are the three methods involved in rotating the image by 90 degrees: 

Project: ImageFilelO I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

void OnRotateLeftAppBarButtonCli ck(object sender, RoutedEventArgs args) 

{ 

Rotate( (Bi tmapSource bitmap, i nt x, int y)=> 

{ 

return 4 * (bitmap.PixelWidth * x + (bitmap.PixelWidth - y - 1)); 

})； 

} 
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void OnRotateRightAppBarButtonCli ck(object sender, RoutedEventArgs args) 

{ 

Rotate((Bi tmapSource bitmap, int x, int y)=> 

{ 

return 4 * (bitmap.PixelWidth * (bitmap.Pixel Height - x - 1) + y); 

}); 

} 

async void Rotate(Func<Bi tmapSource, int, int, int> calculateSourcelndex) 

{ 

// Get the source bitmap pixels 

WriteableBitmap srcBitmap = image.Source as WriteableBitmap; 

byte[] srcPixels = new byte [4 * srcBitmap.PixelWidth * srcBitmap.Pixel Height]; 

using (Stream pi xel Stream = srcBi tmap. Pi xel Buffer. AsStreamO) 

{ 

await pixelStream.ReadAsync(srcPixels, 0 ， srcPixels.Length); 

} 

// Create a destination bitmap and pixels array 

WriteableBitmap dstBitmap = 

new WriteableBitmap (srcBitmap.PixelHeight, srcBitmap.PixelWidth); 
byte[] dstPi xels = new byte [4 * dstBitmap.PixelWidth * dstBi tmap.Pi xelHeight]; 

// Transfer the pixels 
int dstlndex = 0; 

for (int y = 0; y < dstBitmap.PixelHeight; y++) 
for (int x = 0; x < dstBitmap.PixelWidth; x++) 

{ 

int srclndex = calculateSourcelndex(srcBitmap, x, y); 

for (i nt i =0; i <4; i++) 

dstPixels[dstlndex++] = srcPixels[srclndex++]; 


// Move the pixels into the destination bitmap 

using (Stream pi xel Stream = dstBi tmap. Pi xel Buffer. AsStreamO ) 

{ 

await pixelStream.WriteAsync(dstPixels, 0, dstPi xel s.Length); 

} 

dstBitmap.InvalidateC); 

// Swap the DPIs 
double dpi = dpiX; 
dpiX = dpiY; 
dpiY = dpi ; 

// Display the new bitmap 
image.Source = dstBitmap; 

} 

} 
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The bulk of both jobs is handled by the same Rotate method, except that this method has an 
argument that is a function to calculate a source index based on x and y pixel locations of the destina¬ 
tion bitmap. If you try this out on large files, you’ll find that they require a couple seconds to rotate, 
strongly suggesting that routines like this should not be executed in the user-interface thread. 

The rotation could be performed asynchronously by passing that block of nested for loops to Task 
•Run and awaiting the return. However, the asynchronous code cannot access the WriteobleBitmap 
itself. You’ll need to obtain the width and height of the bitmap before executing the asynchronous 
code and to redefine the colculoteSourcelndex to accept a bitmap width and height rather than the 
bitmap. It would also be prudent to disable the application bar buttons during this time to prevent 
any interference with the job before it’s completed. 

Posterize and Monochromize 


Most image-processing programs have an option to "posterize" a bitmap. The color resolution is re¬ 
duced to a limited palette, and this causes the image to resemble a poster rather than a photograph. 
Another common option is to convert an image to monochrome. These two jobs represent perhaps 
the simplest image-processing operations. 

The Posterizer program has Open File and Save As buttons like ImageFilelO, but the page also 
contains a "control panel” — a bunch of RadioButton controls that let you select a number of bits of 
color resolution (independently for the three color channels) and a Check Box to convert the image to 
monochrome. 

Suppose the user loads in a bitmap and clicks the Check Box to convert it to monochrome and the 
program dutifully combines the Red, Green, and Blue values of each pixel into a gray shade. Then the 
user unchecks the CheckBox. Let’s hope your program has saved the original image! This is why the 
Posterizer program maintains two entire pixel arrays, one with the original pixels (named srcPixels for 
"source pixels") and the other with modified pixels (named dstPixels for "destination pixels"). 

The XAML file contains the control panel, an Image element and an application bar: 

Project: Posterizer I File: MainPage.xaml (excerpt) 

<Page … > 

<Page.Resources 〉 

〈Style TargetType="TextBlock"> 

<Setter Property="FontSi ze" Value="18" /> 

〈Setter Property="TextAl ignment" Val ue="Center" /> 

</Style> 

</Page.Resources 〉 


<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Grid.ColumnDefinitions> 

<ColumnDefinition Wi dth="Auto" /> 

<ColumnDefinition Width="*" /> 

</Grid.ColumnDefinitions> 
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〈Grid Name="control PanelGrid" 

Grid.Col umn="0" 

Margin="12 0" 

HorizontalAli gnment="Center" 
VerticalAli gnment="Center"> 

<Grid.ColumnDefini tions> 

<ColumnDefinition Width="*" /> 
<ColumnDefinition Width="*" /> 
<ColumnDefinition Width="*" /> 
<ColumnDefinition Width="*" /> 
</Grid.ColumnDefinitions> 


<Grid.RowDefinitions> 
<RowDefinition 


<RowDefinition 
<RowDefinition 
<RowDefinition 
<RowDefiniti on 
<RowDefinition 
<RowDefini ti on 
<RowDefinition 
<RowDefiniti on 


Height="Auto" /> 
Height="Auto" /> 
Hei ght="Auto" /> 
Height="Auto" /> 
Hei ght="Auto" /> 
Hei ght="Auto" /> 
Height="Auto" /> 
Hei ght="Auto" /> 
Height="Auto" /> 
Hei ght="Auto" /> 


<RowDefinition 
</Grid.RowDefiniti ons> 


〈TextBlock Text="Red" Grid. Row="0" Grid.Col umn="0" /> 
〈TextBlock Text="Green" Grid. Row="0" Grid.Col umn="l" /> 
〈TextBlock Text="Bl ue" Grid. Row="0" Grid.Col umn="2" /> 
〈TextBlock Text="Al1 " Grid. Row="0" Grid.Col umn="B" /> 


<CheckBox Name="monochromeCheckBox" 

Content=. 'Monochrome" 

Grid.Row="9" 

Grid.Col umn="0" 

Grid.Col umnSpan="4" 

Margin= M 0 12" 

HorizontalAli gnment="Center" 
Checked="OnCheckBoxChecked" 
Unchecked="OnCheckBoxChecked" /> 

</Grid> 


<Image Name="image" 

Grid.Col umn="l" /> 

</Gri d> 


<Page.BottomAppBar> 

<AppBar> 

<Gri d> 

<StackPanel Orientati on="Hori zontal" 

HorizontalAli gnment="Ri ght"> 

<Button Style="{StaticResource OpenFileAppBarButtonStyle}" 
Cli ck="0n0penAppBarButtonClick" /> 
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〈Button Name="saveAsButton" 

IsEnabled="False" 

Style="{StaticResource SaveLocalAppBarButtonStyl e} 
AutomationProperties. Name="Save As" 

Cli ck="OnSaveAsAppBarButtonClick" /> 

</StackPanel> 

</Grid> 

</AppBar> 

</Page.BottomAppBar> 

</Page> 


However, the XAML file is missing the actual RodioButton controls. I decided I wanted to 
independently control the three color channels but have a fourth column to change all three color 
channels in one shot. The buttons are created in the Loaded handler with the convenient Tag property 
used to identify them: 


Project: Posterizer I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 


public MainPage() 

{ 

this. InitializeComponent(); 
Loaded += OnLoaded; 

} 


void OnLoaded(object sender, RoutedEventArgs args) 

{ 

// Create the RadioButton controls 
// NOTE: 'a' here means ” All" not "Alpha"! 
string[] prefix = { "r", "g", "b", "a" }; 

for (i nt col = 0; col < 4; col++) 

for (i nt row = 1; row < 9; row++) 

{ 

RadioButton radio = new RadioButton 

{ 

Content = row.ToString(), 

Margin = new Thi ckness(12 , 6 ， 12 ， 6 )， 
GroupName = prefix[col], 

Tag = prefix[col] + row, 

IsChecked = row == 8 

}； 

radio.Checked += OnRadioButtonChecked; 

Grid .SetColumn(radio, col); 

Grid. SetRow(radio, row); 

control PanelGrid.Chi Idren.Add(radio); 

} 

} 

} 
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The file I/O is very similar to the ImageFilelO project, except that when an image is loaded, a 
second array of pixels is created and a method named UpdoteBitmop (which I’ll describe shortly) is 
responsible for updating the WriteableBitmop with this second array of pixels. When a file is saved, the 
dstPixels array is used: 


Project: Posterizer I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

WriteableBitmap bitmap; 

Stream pixel Stream; 
byte[] srcPixels; 
byte[] dstPixels; 

async void OnOpenAppBarButtonCli ck(object sender, RoutedEventArgs args) 

{ 

// Create Fi1eOpenPicker 

Fi1eOpenPicker picker = new Fi1eOpenPi cker() ; 

picker.SuggestedStartLocation = PickerLocationld .PicturesLibrary; 

// Initialize with filename extensions 

IReadOnlyLi st<Bi tmapCodecInformati on> codeclnfos = 

BitmapDecoder. GetDecoderlnformationEnumerator(); 


foreach (Bi tmapCodecInformation codeclnfo in codeclnfos) 
foreach (string extension in codeclnfo.Fi1eExtensions) 
picker.FileTypeFiIter.Add(extension); 


// Get the selected file 

StorageFi1e storageFi1e = await picker.PickSingleFileAsync(); 

if (storageFi1e == null) 
return ; 

// Open the stream and create a decoder 
BitmapDecoder decoder = null; 


using (IRandomAccessStreamWithContentType stream = await storageFile.OpenReadAsyncO) 

{ 

string exception = null; 
try 

decoder = await BitmapDecoder .CreateAsync(stream); 

} 

catch (Exception exc) 

{ 

exception = exc.Message; 

} 

if (exception != null) 

{ 

MessageDialog msgdlg = 

new MessageDial ogC'That particular image file could not be loaded. " + 

"The system reports on error of: " + exception); 
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await msgdlg.ShowAsyncO ; 
return ; 


// Get the first frame 

BitmapFrame bitmapFrame = await decoder.GetFrameAsync(O); 

// Get the source pixels 

PixelDataProvider dataProvider = 

await bitmapFrame.GetPixelDataAsync (Bi tmapPixelFormat. Bgra8, 

BitmapAlphaMode .Premultiplied, 
new BitmapTransformC) , 

ExifOrientationMode. RespectExifOrientation, 
ColorManagementMode .ColorManageToSRgb); 

srcPixels = dataProvider.DetachPixelData(); 
dstPixels = new byte[srcPixels. Length]; 


// Create WriteableBitmap and set as Image source 
bitmap = new WriteableBi tmap((i nt)bi tmapFrame.PixelWidth, 

(i nt) bitmapFrame.PixelHeight); 
pi xel Stream = bitmap. Pixel Buffer. AsStreamO ; 
image.Source = bitmap; 


// Update bitmap from masked pixels 
UpdateBi tmapO ; 

} 

// Enable the Save As button 
saveAsButton.IsEnabl ed = true; 

} 

async void OnSaveAsAppBarButtonCli ck(object sender, RoutedEventArgs args) 

{ 

Fi1eSavePicker picker = new Fi1eSavePi cker() ; 

picker.SuggestedStartLocation = PickerLocationld. PicturesLibrary; 

// Get the encoder information 

Dicti onary<stri ng , Guid> imageTypes = new Dicti onary<stri ng , Gui d>(); 
IReadOnlyList<BitmapCodecInformation> codeclnfos = 

BitmapEncoder .GetEncoderInformationEnumerator(); 


foreach (Bi tmapCodecInformation codeclnfo in codeclnfos) 

{ 

Li st<stri ng> extensions = new Li st<stri ng>() ; 

foreach (string extension in codeclnfo.Fi1eExtensions) 
extensions.Add(extension); 

string fi1etype = codeclnfo.FriendlyName.Split(' ' ) [0]; 
picker.Fi1eTypeChoices.Add(fi1etype, extensions); 

foreach (string mimeType in codeclnfo.MimeTypes) 
imageTypes.Add(mimeType, codeclnfo.Codecld); 

} 
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// Get a selected StorageFi1e 

StorageFi1e StorageFi1e = await picker.PickSaveFileAsyncC); 

if (StorageFi1e == null) 
return ; 


// Open the StorageFi1e 

using (IRandomAccessStream fi1eStream = 

await StorageFi1e.OpenAsync(Fi 1eAccessMode .ReadWrite)) 

{ 

// Create an encoder 

Guid codecld = imageTypes[StorageFi1e.ContentType]; 

BitmapEncoder encoder = await BitmapEncoder .CreateAsync(codecld, fi1eStream); 
// Write the destination pixels to the first frame 

encoder.SetPixelData(Bi tmapPixelFormat. Bgra8, BitmapAlphaMode .Premultipiied, 

(ui nt)bi tmap■PixelWidth ， (ui nt) bitmap.PixelHeight, 

96 ， 96 ， dstPixels); 

await encoder. FI us hAsyncO ; 

} 

} 


The RadioButton event handler turned out to be rather tricky because of that fourth column of 
buttons. I wanted a click on a RadioButton in the fourth column to also check the other three buttons 
in that row, but what I certainly didn’t want was multiple calls to UpdateBitmap. For this reason, an 
array of three byte masks is maintained as a field, and these are set in the RadioButton event handler. 
UpdateBitmap is called only if at least one of these mask values is changed: 


Project: Posterizer I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 


// Byte masks for blue ， green, red 
byte 口 masks = { OxFF, OxFF, OxFF }; 

void OnRadioButtonChecked (object sender, RoutedEventArgs args) 

{ 

// Decode the RadioButton Tag property 
RadioButton radio = sender as RadioButton; 
string tag = radio.Tag as string; 
int masklndex = -1; 

int bits = Int32 .Parse(tag[1].ToString()); // 1 to 8 
byte mask = (byte) (OxFF « 8 - bits); 
bool needsllpdate; 
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// Find the index of the masks array 
switch (tag[0]) 

{ 


case 'r' 

masklndex = 2; 

break; 

case 'g' 

masklndex = 1; 

break; 

case 'b' 

masklndex = 0; 

break; 


} 

// For "A11", check all the other buttons in the row 
if Ctag[0] == 'a') 

{ 

needsUpdate = masks[0] != mask && masks[1] != mask && masks[2] != mask; 
if (needsUpdate) 

masks[0] = masks[1] = masks[2] = mask; 

foreach (UIElement child in (radio.Parent as Panel) .Children) 

{ 

if (child != radio && 

Grid. GetRow(chiId as FrameworkElement) == Grid .GetRow(radio)) 

{ 

(child as RadioButton) .IsChecked = true; 


} 

else 

{ 

needsUpdate = masks[masklndex] != mask; 

if (needsUpdate) 

masks[masklndex] = mask; 

} 

if (needsUpdate) 

UpdateBi tmapO ; 

} 


void OnCheckBoxChecked (object sender, RoutedEventArgs args) 

{ 

UpdateBi tmapO ; 

} 


All that’s left is UpdoteBitmap itself. The three mask values are applied to the blue, green, and red 
components, and then these components are combined to create a gray shade if the Monochrome 
button is checked. The weights for the gray shade are the standard conversion factors for the NTSC 
and PAL color television standards: 

Project: Posterizer I File: MainPage.xaml.es (excerpt) 

void UpdateBi tmapO 

{ 

if (bitmap == null) 
return ; 
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for (int index = 0; index < srcPixels.Length; 'index += 4) 

{ 

// Mask source pixels 

byte B = (byte) (masks[0] & srcPixels[index +0]); 

byte G = (byte) (masks[1] & srcPixels[index +1]); 

byte R = (byte) (masks[2] & srcPixels[index +2]); 

byte A = srcPixels[index + 3]; 

// Possibly convert to gray shade 
if (monochromeCheckBox.IsChecked.Value) 

B = G = R = (byte) (0.30 * R + 0.59 * G + 0.11 * B); 

// Save destination pixels 
dstPixels[index +0] = B; 
dstPixels[index +1] = G; 
dstPixels[index + 2] = R; 
dstPixels[index + 3] = A; 

} 


// Update bitmap 

pixelStream.Seek(0, SeekOrigin .Begin); 

pixel Stream.Write(dstPixels, 0 ， dstPixels.Length); 

bitmap.InvalidateC); 


If this were anything other than a sample program, I would put this processing in a second thread. 
But only the loops that alter the pixel bits should be in that thread. Any modification to the Writeable- 
Bitmap itself must be in the user-interface thread. 

Here it is reducing the pixel resolution of an image to two bits, which means the entire image is 
displayed with just 64 colors: 
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Saving Finger Paint Artwork 

The series of FingerPaint programs I discussed in the previous chapter all had a big drawback: You 
couldn’t save your artwork. I suggested that one approach to saving the image is to enumerate the 
Line or Polyline or Path elements in the Grid and create some kind of text file (probably in an XML 
format) that would allow you to re-create all the elements when the file is reloaded. 

Or you can draw on a bitmap and save that. The big problem here, however, is that the Windows 
Runtime version of WriteableBitmap doesn't support the rendering of elements such as Line and Path. 
You basically have to implement your own line- and arc-drawing algorithms. For a set of line-drawing 
coordinates and other parameters, these algorithms must figure out what pixels in the bitmap should 
be set to render these graphical objects. 

Let’s suppose you want to draw a line between two points: 



A geometric line has zero width, but a rendered line must have a non-zero width, and in a 
finger-painting program, the width might be considerable (for example, 24 pixels). We really want to 
render this line by drawing a rectangle that extends on each side of the geometric line by half the 
total line width, 12 pixels on each side in this example: 



The four corners of that rectangle can be derived fairly easily by rotating the normalized vector 
between the two geometric points by 90 and -90 degrees and multiplying by half the total line 
thickness. 
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But if you’re drawing one of these rectangles for each PointerMoved event, they're not going to 
join correctly for a curved line. Little gaps will appear. To avoid those gaps, you want to draw rounded 
caps on this rectangle: 



The radius of each of these arcs is half the total line thickness. 

The overall shape consists of two arcs connected with two lines. (A similar shape is involved if the 
line increases or decreases in width between the two points, as I showed in the previous chapter.) 

But we don’t want to draw that outline as I’ve done here. We need to fill the interior, which means 
coloring every pixel that appears within the overall shape. 

From high school you are probably familiar with the equation for a line in the slope-intercept form: 

y = mx + b 

where m is the slope ("rise over run") and b is the value of y where the line intercepts the Y axis. 

In traditional computer graphics, however, areas are filled based on horizontal scan lines, also 
known as raster lines. (The terms come from television technology.) The line equation should 
represent x as a function of y: 

x = ay -\-b 

For a line from ptl to pt2, you can calculate a and b like so: 

_ ptl.X - ptl.X 
ptl.Y - ptl.Y 

b = ptl.X-a - ptl.Y 

For any y (that is, for any scan line), if y is between ptl.Y and pt2_Y, that value of y corresponds to a 
point on the line. The x coordinate of that point can be calculated from the equation of the line. 

Look at the most recent diagram, and imagine horizontal scan lines intercepting the figure. For any 
y we can determine if the scan line crosses one or both of the outer two lines. If so, we can calculate 
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x values for those two points. All the pixels between those x values must then be colored. This can be 
repeated for each y. 


The process gets a little messier if the scan line passes through the rounded caps, but not much 
messier. A circle of radius r centered on the origin consists of all points [x, y) that satisfy the equation: 



For a circle centered on the point [x c , y c ), the equation is: 



Or, expressed as a function of y, 



For any y, if the expression in the square root is negative, then y is outside the circle entirely — 
somewhere above or below the circle. Otherwise, there are (in general) two values of x for every y. 
The only exception is when the square root is zero, which happens when y is exactly r units from y c , 
which are the top and bottom points of the circle. 

When dealing with an arc that goes only partway around the circle, it gets a little more complex. 
Any point on an arc forms an angle from the center of the circle. That angle can be calculated 
with the Math.Atan2 method. If we know the start point and end point of the arc, Moth.Aton2 can 
calculate the angles corresponding to those two points. You can also use Math.Atan2 to calculate the 
angle of any arbitrary point on the circle. If that point on the circle is between the start point and end 
point, the point is on the arc. 

In general, for any y we can examine the two lines and two arcs and determine all points [x, y) that 
coincide with these four figures. At most, there will be only two such points: one where the scan line 
enters the figure and one where it exits. For that scan line, all pixels between these two points can be 


filled. 


The FingerPaint solution contains a library project named Petzold. Windows8.VectorDrowing that 
contains several structures to implement line drawing on bitmaps. (I made them structures rather 
than classes because they will be instantiated and discarded very frequently.) 

You’ve already seen the Vector2 structure included in this library. All the other structures 
implement this little interface: 

Project: Petzold.Windows8.VectorDrawing | File: IGeometrySegment.es 
using System.Col 1ections. Gene ric ; 

namespace Petzold.Windows8.VectorDrawing 
{ 

public interface IGeometrySegment 


void GetAl lX(doubl e y, Hi st<double> xCollection); 
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} 


For any y, the GetAIIX method adds items to a collection of x values. In actual practice, using 
the structures in the library that implement this interface, often this collection is returned empty. 
Sometimes it contains one item, and sometimes two. 

Here’s the LineSegment structure: 


Project: Petzold.Windows8.VectorDrawing I File: LineSegment.es 

using System.Col 1ections.Generic; 
using W~indows■ Foundation; 


namespace Petzold.Windows8.VectorDrawing 
{ 

public struct LineSegment : IGeometrySegment 
{ 

readonly Point pointl ， point2; 

readonly double a, b; // as in x = ay + b 

public LineSegment(Poi nt pointl ， Point point2) : thi s() 

{ 

this. pointl = pointl; 
this. point2 = point2; 

a = (point2.X - pointl.X) / (point2.Y - pointl.Y); 
b = pointl.X - a * pointl.Y; 

} 

public void GetAllX(double y, ILi st<double> xCollection) 

{ 

if ((point2.Y > pointl.Y && y >= pointl.Y && y < point2.Y) || 
(point2.Y < pointl.Y && y <= pointl.Y && y > point2.Y)) 

{ 

xCollection.Add(a * y + b); 



Notice that the //statement in GetAIIX checks if y is between pointl.Y and point2.Y. It allows y 
values that equal pointl.Y but not those that equal point2.Y. In other words, it defines the line to be all 
points from poi ntl (inclusive) up to but not including point2. It helps to exercise some strict rules and 
caution in this regard. Otherwise, when dealing with connected lines and arcs, we’ll get duplicate x 
values in the collection, and that makes the job harder. 

No special consideration is given to horizontal lines, which are lines where pointl.Y equals point2.Y 
and a equals infinity. In that case, the //statement is never satisfied and the line is ignored. A scan line 
never crosses a horizontal boundary line. 
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The ArcSegment structure is a generalized arc on the circumference of a circle: 

Project: Petzold.Windows8.VectorDrawing | File: ArcSegment.cs 
using System; 

using System.Col 1ections.Generic; 
using Windows■Foundation; 


namespace Petzold.Windows8.VectorDrawing 

{ 

public struct ArcSegment : IGeometrySegment 

{ 

readonly Point center, pointl, point2; 
readonly double radius; 
readonly double anglel, angle2; 


public ArcSegment (Poi nt center, double radius, 

Point pointl, Point point2) : 

this() 

{ 

this. center = center; 


this. radius 
this. pointl 
this. point2 
this .anglel 
this. angle2 


radius; 
pointl; 
point2; 

Math.Atan2(pointl.Y - center.Y, pointl.X - center.X); 
Math. Atan2(point2.Y - center.Y, point2.X - center.X); 


public void GetAllX (double y, Hi st<double> xCollection) 

{ 

double sqrtArg = radius * radius - Math. Pow(y - center.Y, 2); 


if (sqrtArg >= 0) 

{ 

double sqrt = Math .Sqrt(sqrtArg); 
TryY(y, center.X + sqrt, xCollection); 
TryYCy, center.X - sqrt, xCollection); 



void TryY(double y, double x, Hi st<double> xCollection) 

{ 

double angle = Math .Atan2(y - center.Y, x - center.X); 


if ((anglel < angle2 && (anglel <= angle && angle < angle2)) 
(anglel > angle2 && (anglel <= angle || angle < angle2))) 

{ 

xCollection.Add((float)x); 



The rather complex (but symmetrical) //clause in TryY accounts for the wrapping of angle values 
from n to -n and back again. The comparison of angle with anglel and ongle2 implies that a scan line 
is considered to intersect the arc when angle equals anglel but not when angle equals angle2. 
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The GetAIIX method in LineSegment puts either zero or one x value in the collection. The GetAIIX 
method in ArcSegment can put zero, one, or two x values in the collection. The RoundCoppedLine 
structure combines two LineSegment instances and two ArcSegment instances for the case of a line 
with uniform thickness: 


Project: Petzold.Windows8.VectorDrawing I File: RoundCappedLine.es 

using System.Col 1ections.Generic; 
using Windows.Foundation; 


namespace Petzold.Windows8.VectorDrawing 

{ 

public struct RoundCappedLine : IGeometrySegment 

{ 

LineSegment 1ineSegmentl; 

ArcSegment arcSegmentl; 

LineSegment 1ineSegment2; 

ArcSegment arcSegment2; 


public RoundCappedLine(Poi nt pointl, Point point2, double radius) : thi s() 

{ 

Vector2 vector = new Vector2(point2 - new Vector2(pointl)); 

Vector2 normVect = vector; 
normVect = normVect.Normalized; 

Point ptla = pointl + radius * new Vector2 (normVect.Y, -normVect.X); 
Point pt2a = ptla + vector; 

Point ptlb = pointl + radius * new Vector2(-normVect.Y, normVect.X); 
Point pt2b = ptlb + vector; 


} 


lineSegmentl = new Li neSegment(ptla, pt2a); 
arcSegmentl = new ArcSegment (point2 ， radius, 
1ineSegment2 = new Li neSegment(pt2b , ptlb); 
arcSegment2 = new ArcSegment(poi ntl, radius, 


pt2a, 

ptlb, 


Pt2b); 
ptla); 


public void GetAllX(double y, ILi st<double> xCollection) 

{ 

arcSegmentl.GetAHX(y, xCollection); 

1ineSegmentl.GetAllX(y, xCollection); 
arcSegment2.GetAllX(y, xCollection); 

1 ineSegment2.GetAllX(y, xCollection); 

} 



This structure implements GetAIIX by calling the GetAIIX methods in the two LineSegment 
instances and two ArcSegment instances. It is the responsibility of the code calling GetAIIX in this 
structure to ensure that the collection has previously been cleared. The method returns a collection 
with zero, one, or two x values. The case of zero or one x value can be ignored for filling purposes. For 
two x values, the pixels between those two values can be filled. 
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The RoundCoppedPath structure is similar except that it allows a line to have a different thickness 
at the beginning and at the end on a pressure-sensitive touch screen: 

Project: Petzold.Windows8.VectorDrawing | File: RoundCappedPath.es 
using System; 

using System.Col 1ections.Generic; 
using Windows■Foundation; 


namespace Petzold.Windows8.VectorDrawing 

{ 

public struct RoundCappedPath : IGeometrySegment 

{ 

LineSegment 1 ineSegmentl; 

ArcSegment arcSegmentl; 

LineSegment 1 ineSegment2; 

ArcSegment arcSegment2; 


public RoundCappedPath(Poi nt pointl, Point point2, double radiusl ， double radius2) 
: this() 

{ 

Point cO = pointl; 

Point cl = point2; 
double rO = radiusl; 
double rl = radius2; 

// Get vector from cl to cO 

Vector2 vCenters = new Vector2(cO) - new Vector2(cl) ; 

// Get length and normalized version 
double d = vCenters.Length; 
vCenters = vCenters.Normalized; 

// Create focal point F extending from cO 
double e = d * rO / (rl - rO); 

Point F = cO + e * vCenters; 


// Find angle and "length of right-triangle "legs 
double alpha = 180 * Math. Asin(rO / e) / Math .PI; 
double legO = Math.Sqrt(e * e - rO * rO); 
double legl = Math.Sqrt((e + d) * (e + d) - rl * rl); 

// Vectors of tangent "lines 

Vector2 vRight = -vCenters.Rotate(alpha); 

Vector2 vLeft = -vCenters.Rotate(-alpha); 

// Find tangent points 

Point tOR = F + legO * vRight; 

Point tOL = F + legO * vLeft; 

Point tlR = F + legl * vRight; 

Point tlL = F + legl * vLeft; 

lineSegmentl = new Li neSegment(tlR, tOR); 
arcSegmentl = new ArcSegment (cO, rO, tOR, tOL); 

1ineSegment2 = new LineSegment (tOL, tlL); 
arcSegment2 = new ArcSegment(cl, rl, tlL, tlR); 
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public void GetAllX (double y, ILi st<double> xCollection) 

{ 

arcSegmentl.GetAllX(y, xCollection); 

1ineSegmentl.GetAllX(y, xCollection); 
arcSegment2.GetAllX(y, xCollection); 

1ineSegment2.GetAllX(y, xCollection); 

} 



I adapted some of this logic from the FingerPaint5 program in the previous chapter. 

Using these structures in an actual program is not as easy as instantiating Line or Polyline or Path\ 
Here is the RenderOnBitmop method from FingerPaint. This method makes use of a WriteableBitmap 
named bitmap, with a pixel array named pixels, and a Stream object named pixelStream. The method 
begins by determining whether it should use RoundCappedLine or RoundCoppedPath: 

Project: FingerPaint I File: MainPage.Pointer.es (excerpt) 

public sealed partial class MainPage : Page 


bool RenderOnBitmap(Poi nt pointl， double radiusl， Point point2, double radius2, Col or color) 

{ 

bool bitmapNeedsUpdate = false; 


// Define a line between the two points with rounded caps 

IGeometrySegment geoseg = null; 

// Adjust the points for any bitmap scaling 
Point centerl = SealeToBitmapCpointl); 

Point center2 = SealeToBitmapCpoint2); 

// Find the distance between them 

double distance = Math .Sqrt(Math.Pow(center2.X - centerl.X, 2) + 

Math. Pow(center2.Y - centerl.Y, 2)); 


// Choose the proper way to render the segment 
if (radiusl == radius2) 

geoseg = new RoundCappedLi ne(centerl, center2, radiusl); 

else if (radiusl < radius2 && radiusl + distance < radius2) 
geoseg = new RoundCappedLi ne(centerl, center2, radius2); 


else if (radius2 < radiusl && radius2 + distance < radiusl) 
geoseg = new RoundCappedLi ne(centerl, center2, radiusl); 

else if (radiusl < radius2) 

geoseg = new RoundCappedPath (centerl, center2, radiusl, radius2) 


else 


geoseg = new RoundCappedPath(center2 , centerl, radi us2, radi usl) 
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// Find the minimum and maximum vertical coordinates 
int yMin = (i nt)Math .Min(centerl.Y - radiusl, center2.Y - radius2); 
int yMax = (i nt)Math .Max(centerl.Y + radiusl, center2.Y + radiusl); 

yMin = Math. Max(0 ， Math .Min(bitmap.PixelHeight ， yMin)); 
yMax = Math. Max(0 ， Math .Min(bitmap.PixelHeight ， yMax)); 


// Loop through all the y coordinates that contain part of the segment 
for (int y = yMin; y < yMax; y++) 

{ 

// Get the range of x coordinates in the segment 

xCollection.Clear(); 

geoseg.GetAl1X(y, xCollection); 

if (xCol1ection.Count == 2) 

{ 

// Find the minimum and maximum horizontal coordinates 

int xMin = (i nt) (Math. Min(xCol1ection[0], xCollection[l]) + 0.5f); 

int xMax = (int) (Math. Max(xCollection[0], xCollection[l]) + 0.5f); 

xMin = Math .Max(0, Math .Min(bitmap.PixelWidth, xMin)); 
xMax = Math .Max(0, Math .Min(bitmap.PixelWidth, xMax)); 

// Loop through the X values 
for (int x = xMin; x < xMax; x++) 


// Set the pixel 

int index = 4 * (y * bitmap.PixelWidth + x); 

pixels[index + 0] = color.B; 

pixels[index + 1] = color.G; 

pixels[index + 2] = color.R; 

pixels[index + 3] = 255; 

bitmapNeedsUpdate = true; 

} 


} 

// Update bitmap 
if (bitmapNeedsUpdate) 

{ 

// Find the starting index and number of pixels 

int start = 4 * yMin * bitmap.PixelWidth; 

int count = 4 * (yMax - yMin) * bitmap.Pixel Width; 

pixelStream.Seek(start, SeekOrigin. Begin); 
pixelStream.WriteCpixels, start, count); 
bitmap.Invalidate(); 

} 


return bitmapNeedsUpdate; 

} 
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Point SealeToBitmap(Poi nt pt) 


return new Poi nt((pt.X - imageOffset.X) / imageScale, 

(pt.Y - imageOffset.Y) / imageScale); 


Notice that the RenderOnBitmap concludes by restricting the updating to only the scan lines 
affected by this particular drawing operation. The ScoleToBitmop method adjusts points for bitmaps 
that are larger or smaller than the program’s current page size. 


To organize the source code files in the FingerPaint project in functional chunks, I’ve divided the 
code-behind logic for MainPage into three files: the normal MainPage.xaml.es; MainPage.Pointer.es, 
which contains all the Pointer event handling (including the RenderOnBitmap method I just showed 
you); and MainPage.File.es, which contains the file I/O. The remainder of MainPage.Pointer.es should 
look very familiar. Aside from the call to RenderOnBitmap, it’s mostly the same as FingerPaint5: 


Project: FingerPaint I File: MainPage.Pointer.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

struct Pointerlnfo 

{ 

public Brush Brush; 

public Point PreviousPoint; 

public double PreviousRadius; 

} 

Dicti onary<ui nt , Pointerlnfo pointerDictionary = new Dicti onary<ui nt , PointerInfo>() ; 
Li st<double> xCol1ection = new Li st<doubl e>() ; 


protected override void OnPointerPressed(Poi nterRoutedEventArgs args) 

{ 

// Get information from event arguments 
uint id = args.Pointer.Poi nterld; 

PointerPoint pointerPoint = args.GetCurrentPoi nt(this) ; 

// Create Pointerlnfo 

Pointerlnfo pointerlnfo = new Pointerlnfo 

{ 

PreviousPoint = pointerPoint.Position, 

PreviousRadi us = appSettings.Thickness * pointerPoint.Properties.Pressure, 
Brush = new Sol idCol orBrush (appSettings.Col or) 

}； 

// Add to dictionary 

pointerDictionary.Add(id, pointerlnfo); 

// Capture the Pointer 
CapturePointer(args.Poi nter); 

base. OnPointerPressed(args); 
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protected override void OnPointerMoved(Poi nterRoutedEventArgs args) 

{ 

// Get ID from event arguments 
uint id = args.Pointer.Pointerld; 

// If ID is in dictionary, start a loop 
if (pointerDictionary.ContainsKey(id)) 

{ 

Pointerlnfo pointerlnfo = pointerDictionary[id]; 

foreach (Poi nterPoi nt poi nterPoi nt in args .Getlntermedi ate Poi nts(thi s) . ReverseO) 

{ 

// For each point, get new position and pressure 
Point point = pointerPoint.Position; 

double radius = appSettings.Thickness * pointerPoint.Properties.Pressure; 

// Render and flag that it's modified 
appSettings.IsImageModified = 

RenderOnBitmap(pointerlnfo.PreviousPoint ， pointerlnfo.PreviousRadius, 

point, radius, 
appSettings.Color); 

// Update Pointerlnfo 

pointerlnfo.PreviousPoint = point; 

pointerlnfo.PreviousRadius = radius; 


// Store Pointerlnfo back in dictionary 
pointerDictionary[id] = pointerlnfo; 

} 

base. OnPointerMoved(args); 


protected override void OnPointerReleased(Poi nterRoutedEventArgs args) 

{ 

// Get information from event arguments 
uint id = args.Poi nter .Poi nterld; 

// If ID is in dictionary, remove it 
if (pointerDictionary.ContainsKey(id)) 
pointerDictionary.Remove(id); 

base. OnPointerReleased(args); 

} 


protected override void OnPointerCaptureLost(Poi nterRoutedEventArgs args) 

{ 

// Get information from event arguments 
uint id = args.Pointer.Pointerld; 

// If ID is still in dictionary, remove it 
i f (poi nterDi ctionary .Contai nsl<ey(i d)) 
pointerDictionary.Remove(id); 

base. OnPointerCaptureLost(args); 

} 
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Both On Poin ter Pressed and OnPointerMoved reference a field named oppSettings of type 
AppSettings. This object saves settings in application local storage when the program is suspended, 
and it loads them back in when the program starts up. The overall structure of this class should look 
familiar by this point: 


Project: FingerPaint I File: AppSettings.es 

using System.ComponentModel; 
using System.Runtime.Compi1erServices; 
using Windows.Storage; 
using Windows.UI; 


namespace FingerPaint 

{ 

public cl ass AppSettings : INotifyPropertyChanged 

{ 

// Application settings initial values 
string loadedFilePath = null; 
string loadedFilename = null; 
bool islmageModified = false; 

Color color = Colors. Blue; 
double thickness = 16; 


public event PropertyChangedEventHandler PropertyChanged; 


public AppSettingsO 

{ 

ApplicationDataContainer appData = ApplicationData .Current.LocalSettings; 

if (appData.Values.Contai nsKey("LoadedFi 1ePath")) 

thi s .LoadedFi 1 ePath = (string) appData.Values ["LoadedFi1ePath"] ; 

if (appData.Values.Contai nsKey("LoadedFi 1 ename")) 

this .LoadedFi1ename = (stri ng)appData.Values ["LoadedFi1ename"] ; 

if (appData.Values.ContainsKey ("IsImageModifi ed")) 

this .IsImageModified = (bool )appData.Values ["IsImageModified"] ; 

if (appData.Values.ContainsKey ("Color.Red") && 
appData.Values.ContainsKey ("Color.Green") && 
appData.Values.Contai nsKeyC'Color. B1 ue")) 

{ 

this .Color = Color. FromArgb(255, 

(byte) appData.Values ["Color■Red"] , 

(byte) appData.Values ["Color .Green "] ， 
(byte) appData.Values ["Color.Blue"]) ; 

} 

if (appData.Values.Contai nsKeyC'Thi ckness")) 

this .Thickness = (doubl e) appData.Values ["Thickness"] ; 


public string LoadedFi1ePath 

{ 

set { SetProperty<stri ng>(ref loadedFilePath, value); } 
get { return loadedFilePath; } 
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} 

public string LoadedFi1ename 

{ 

set { SetProperty<stri ng>(ref loadedFitename, value); } 
get { return loadedFilename; } 

} 

public bool IsImageModified 

{ 

set { SetPrope rty<bool>( ref islmageModified, value); } 
get { return islmageModified; } 

} 

public Color Color 

{ 

set { SetPrope rty<Color>( ref color, value); } 
get { return color; } 

} 

public double Thickness 

{ 

set { SetProperty<doubl e>(ref thickness, value); } 
get { return thickness; } 

} 


public void Save() 

{ 

ApplicationDataContainer appData = ApplicationData. Current.LocalSettings; 
appData.Values.Clear(); 

appData.Values.Add ("LoadedFilePath " ， this .LoadedFi1ePath); 
appData.Values.Add ("LoadedFi1ename" , this .LoadedFi1ename); 
appData.Values. Add(”IsImageModified" , this. IsImageModified); 
appData.Values.Add ("Color.Red" , this .Color.R); 
appData.Values.Add ("Color.Green" , this. Color.G); 
appData.Values.Add ("Col or.Blue" , this. Col or.B); 
appData.Values. Add("Thi ckness" , this .Thickness); 

} 

protected bool SetProperty<T>(ref T storage, T value, 

[CallerMemberName] string propertyName = null) 

{ 

if (object .Equals(storage, value)) 
return false; 

storage = value; 

OnPropertyChanged(propertyName); 
return true; 

} 


protected void OnPropertyChanged(stri ng propertyName) 

{ 

if (PropertyChanged != null) 

PropertyChanged (thi s , new PropertyChangedEventArgs (propertyName)); 

} 
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One way you can use FingerPaint is to load in existing files, draw on them, and then save them. 

If that’s what you’re doing, the filename and full file path are part of user settings. If instead you’ve 
started with a blank canvas, the LoodedFilenome and LoadedFilePath properties will both be null. 
Regardless, the IsImogeModifiecJ property is true if the image has been modified without being saved 
to a named file. 

In accordance with the concept of chromeless applications, the MainPage.xaml file simply 
instantiates an Image element and implements an application bar: 


Project: FingerPaint I File: MainPage.xaml (excerpt) 

<Page … > 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Image Name="image" /> 


<!-- Disable file I/O buttons in the Snapped state --> 

<VisualStateManager.VisualStateGroups> 

<VisualStateGroup x : Name="Appl icationViewStates"> 

<VisualState x:Name="Ful IScreenLandscape" /> 

〈VisualState x:Name=" Filled" /> 

<VisualState x: Name=" Full ScreenPortrait" /> 

<VisualState x:Name="Snapped"> 

<Storyboard> 

<ObjectAnimationllsi ngKeyFrames Storyboard .TargetName="fi 1 eButtons" 

Storyboard■TargetProperty=" Vi sibility"> 
<DiscreteObjectKeyFrame KeyTime="0" Value="Col lapsed" /> 

</Obj ectAni mati onllsi ngKeyFrames> 

</Storyboard> 

</VisualState> 

</VisualStateGroup> 

</VisualStateManager.VisualStateGroups> 

</Gri d> 

<Page.BottomAppBar> 

<AppBar> 

<Gri d> 

<StackPanel Orientati on="Hori zontal" 

HorizontalA1i gnment="Left"> 

<Button Style="{StaticResource AppBarButtonStyle}" 

AutomationProperties. Name="Color" 

Content="&#xlF308 ;" 

Cli ck="OnCol orAppBarButtonCIick" /> 

<Button Style="{StaticResource EditAppBarButtonStyl e}" 

AutomationProperties. Name="Thi ckness" 

Cli ck="OnThi cknessAppBarButtonCl i ck" /> 

</StackPanel > 


<StackPanel Name="fi 1eButtons" 

Orientati on="Hori zontal" 

HorizontalA1i gnment="Ri ght"> 
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〈Button Style="{StaticResource OpenFileAppBarButtonStyle}" 
Cli ck="OnOpenAppBarButtonClick" /> 

〈Button Style="{StaticResource SaveLocalAppBarButtonStyle} 
AutomationProperties. Name="Save As" 

Cli ck="OnSaveAsAppBarButtonClick" /> 

〈Button Style="{StaticResource SaveAppBarButtonStyl e}" 

Cli ck="OnSaveAppBarButtonClick" /> 


〈Button Style="{StaticResource AddAppBarButtonStyle} 
Cli ck="OnAddAppBarButtonClick" /> 
</StackPanel> 

</Grid> 

</AppBar> 

</Page.BottomAppBar> 

</Page> 


Notice the Visual State Manager markup that makes all the file I/O buttons on the application bar 
disappear when the application is in the Snapped state. This is actually rather more important than 
just avoiding overlapping buttons: The file pickers don’t work in the Snapped state. 

When putting this program together, I encountered a little issue involving file I/O and restarting 
an application after it’s been terminated. Suppose the user invokes the FileOpenPicker to select an 
existing file from the Pictures library. The program gets a StorogeFile object back from FileOpenPicker, 
uses that to open the file, and retains the StorogeFile object as a field. Then, when the user presses 
the Save button on the application bar, the program can simply use that existing StorogeFile object to 
save the file. 

However, suppose the program is suspended, terminated, and later restarted. That StorogeFile 
object cannot be saved in local application storage! The program must abandon it and instead 
compensate by saving the full file path of the file (as I’ve done in the AppSettings class). When 
the program starts up again, and the user presses the Save button, the application doesn’t 
have a StorogeFile object for that file. Instead it must create one using the static StorogeFile. 

G e tFile From Pa thA syn c method. But using this method means that the program is accessing the file 
system without using a StorogeFile object obtained from a file picker. 

For this reason, the FingerPaint program needs permission to access the Pictures library. In Visual 
Studio, I displayed the properties of Package.appxmanifest and selected the Capabilities tab and 
checked Pictures Library. I didn’t want the program to need this special permission, but the only 
alternative was forcing the user to save a previously loaded file by using FileSavePicker. 

Here’s the MainPage.File.es file. You’ll recognize some of the bitmap loading and saving logic 
from previous programs in this chapter, as well as some logic from the XamICruncher application in 
Chapter 8, "App Bars and Popups,” for asking the user to save a picture that’s been modified: 

Project: FingerPaint I File: MainPage.File.es (excerpt) 

public sealed partial class MainPage : Page 
{ 

WriteableBitmap bitmap; 

Stream pixel Stream; 
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byte[] pixels; 


async Task CreateNewBitmapAndPixelArrayO 

{ 

bitmap = new WriteableBi tmap((i nt)this .ActualWidth, (int)this. Actual Height); 
pixels = new byte [4 * bitmap.PixelWidth * bitmap.PixelHeight]; 


// Set whole bitmap to white 

for (i nt index = 0; index < pixels■Length; index++) 
pixels[index] = OxFF; 

await InitializeBitmapC); 

appSettings.LoadedFi1ePath = null; 
appSettings.LoadedFi1ename = null; 
appSettings.IsImageModified = false; 

} 

async Task LoadBitmapFromFi1 e(StorageFi1e storageFi 1 e) 

{ 

using (IRandomAccessStreamWithContentType stream = await storageFile.OpenReadAsyncO) 

{ 

BitmapDecoder decoder = await BitmapDecoder .CreateAsync(stream); 

BitmapFrame bitmapframe = await decoder.GetFrameAsync(O); 

PixelDataProvider dataProvider = 

await bitmapframe.GetPixelDataAsync(Bi tmapPixelFormat. Bgra8, 

BitmapAlphaMode .Premultipiied, 
new BitmapTransformO , 

ExifOri entationMode. RespectExifOrientation, 
ColorManagementMode. ColorManageToSRgb); 

pixels = dataProvider.DetachPi xel Data(); 

bitmap = new WriteableBi tmap((i nt)bi tmapframe.PixelWidth, 

(int)bi tmapframe.PixelHeight); 

await InitializeBitmap(); 



async Task InitializeBitmapO 

{ 

pi xel Stream = bitmap. PixelBuffer.AsStreamO ; 
await pixel Stream.WriteAsyncCpixels, 0 ， pixels.Length); 
bitmap.Invalidate(); 
image.Source = bitmap; 

CalculatelmageScaleAndOffset(); 


async void OnAddAppBarButtonCli ck(object sender, RoutedEventArgs args) 

{ 

Button button = sender as Button ; 
button.IsEnabled = false; 

await ChecklfOkToTrashFile(CreateNewBitmapAndPixelArray); 

button.IsEnabled = true ; 

this .BottomAppBar.IsOpen = false; 


CHAPTER 14 Bitmaps 


737 


async void OnOpenAppBarButtonCli ck(object sender, RoutedEventArgs args) 

{ 

Button button = sender as Button ; 
button.IsEnabled = false; 

await ChecklfOkToTrashFile(LoadFileFromOpenPicker); 

button.IsEnabled = true ; 
this.BottomAppBar.IsOpen = false; 


async Task ChecklfOkToT rashFi 1 e (Func<Tasl<> commandAction) 

{ 

if (!appSettings.IsImageModified) 

{ 

await commandActionO; 
return ; 

} 

string message = 

String .Format("Do you want to save changes to {0 }?"， 

appSettings.LoadedFi1ePath ?? "(untitled)"); 

MessageDialog msgdlg = new MessageDialog (message, "Finger Paint"); 
msgdlg.Commands.Add (new UICommand("Save" , null, "save ")) ； 
msgdlg.Commands.Add (new UICommand("Don 't Save" , null, "dont ")) ； 
msgdlg.Commands.Add (new UlCommand (” Cancel' 1 ， null, "cancel ”））； 
msgdlg.DefaultCommandlndex = 0; 
msgdlg.CancelCommandlndex = 2; 

IUICommand command = await msgdlg.ShowAsyncO; 

if ((stri ng)command.Id == "cancel ") 
return ; 

if ((stri ng)command.Id == "dont") 

{ 

await commandAction O; 
return ; 

} 

if (appSettings.LoadedFi1ePath == null) 

{ 

StorageFi 1 e storageFile = await GetFileFromSavePickerO ; 

if (storageFi1e == null) 
return ; 

appSettings.LoadedFi1ePath = storageFile.Path; 
appSettings.LoadedFi1ename = storageFile.Name; 

} 

string exception = null; 
try 

await SaveBitmapToFile(appSettings.LoadedFi 1 ePath); 

} 
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catch (Exception exc) 

{ 

exception = exc.Message; 

} 

if (exception != null) 

{ 

msgdlg = new MessageDi alogC'The image file could not be saved. " + 

"The system reports an error of: " + exception, 
"Finger Paint"); 

await msgdlg.ShowAsync(); 
return ; 

} 


await commandAction(); 

} 


async Task LoadFi1eFromOpenPicker() 

{ 

// Create Fi1eOpenPicker 

Fi1eOpenPicker picker = new Fi1eOpenPi cker() ; 

picker.SuggestedStartLocation = PickerLocationld .PicturesLibrary; 

// Initialize with filename extensions 

IReadOnlyList<BitmapCodecInformation> codeclnfos = 

BitmapDecoder .GetDecoderlnformationEnumerator(); 


foreach (BitmapCodecInformation codeclnfo in codeclnfos) 
foreach (string extension in codeclnfo.Fi1eExtensions) 
picker.FileTypeFilter.Add(extensi on); 

// Get the selected file 

StorageFi1e storageFi1e = await picker.PickSingleFileAsync(); 

if (storageFi1e == null) 
return ; 

string exception = null; 


try 


await LoadBitmapFromFi1e(storageFi1e); 

} 

catch (Exception exc) 

{ 


} 


exception = exc.Message; 


if (exception != null) 

{ 

MessageDialog msgdlg = 

new MessageDi alogC'The image file could not be loaded. " + 

"The system reports an error of: " + exception, 
"Finger Paint"); 
await msgdlg.ShowAsync(); 
return ; 


} 
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appSettings.LoadedFi1ePath = storageFi1e.Path; 
appSettings.LoadedFi1ename = storageFile.Name; 
appSettings.IsImageModifi ed = false; 

} 

async void OnSaveAppBarButtonCli ck(object sender, RoutedEventArgs args) 

{ 

Button button = sender as Button ; 
button.IsEnabled = false; 

if (appSettings.LoadedFi1ePath != null) 

{ 

await SaveWithErrorNotification(appSettings.LoadedFi 1 ePath); 

} 

else 

{ 

StorageFi 1 e storageFi le = await GetFileFromSavePickerO ; 

if (storageFi1e == null) 
return ; 

await SaveWithErrorNotification(storageFi1e); 

} 

button.IsEnabled = true ; 

} 

async void OnSaveAsAppBarButtonCli ck(object sender, RoutedEventArgs args) 

{ 

StorageFi 1 e storageFi 1 e = await GetFileFromSavePickerO; 

if (storageFi1e == null) 
return ; 

await SaveWithErrorNotification(storageFile); 

} 

async Tasl«StorageFi 1 e> GetFileFromSavePickerO 

{ 

Fi1eSavePicker picker = new Fi1eSavePi cker() ; 

picker.SuggestedStartLocation = PickerLocationld. PicturesLibrary; 

picker.SuggestedFi1eName = appSettings.LoadedFi1ename ?? "MyFingerPainting" ; 

// Get the encoder information 

Dicti onary<stri ng , Guid> imageTypes = new Dicti onary<stri ng , Gui d>(); 
IReadOnlyLi st<Bi tmapCodecInformation> codeclnfos = 

BitmapEncode r. GetEncoderlnformationEnumerator(); 

foreach (Bi tmapCodecInformation codeclnfo in codeclnfos) 

{ 

Li st<stri ng> extensions = new Li st<stri ng>() ; 

foreach (string extension in codeclnfo.Fi1eExtensions) 
extensions.Add(extension); 

string filetype = codeclnfo.FriendlyName.SplitC' ' ) [0]; 


740 PART: Specialties 


picker.Fi1eTypeChoices.Add(fi1etype ， extensions); 


foreach (string mimeType in codeclnfo.MimeTypes) 
imageTypes.Add(mimeType, codeclnfo.Codecld); 

} 

// Get a selected StorageFi1e 

return await picker.PickSaveFi1eAsync(); 

} 

async Task<bool> SaveWithErrorNotificati on(stri ng filename) 

{ 

StorageFi1e StorageFi1e = await StorageFi1e .GetFi1eFromPathAsync(fi1ename); 
return await SaveWithErrorNotification(storageFi1e); 


async Tasl«bool > SaveWithErrorNotificati on(StorageFi 1e StorageFi1e) 

{ 

string exception = null; 



await SaveBitmapToFi1e(storageFi1e); 

} 


catch (Exception exc) 

{ 

exception = exc.Message; 

} 


if (exception != null) 

{ 

MessageDialog msgdlg = 

new MessageDi alogC'The image file could not be saved. " + 

"The system reports an error of: " + exception ， 
” Finger Paint"); 
await msgdlg.ShowAsync(); 
return false; 

} 


appSettings.LoadedFi1ePath = StorageFi1e.Path; 
appSettings.IsImageModified = false; 
return true; 


async Task SaveBitmapToFi1e (string filename) 

{ 

StorageFi 1 e StorageFi1e = await StorageFi 1e .GetFi1eFromPathAsync(fi1ename); 
await SaveBitmapToFi1e(storageFi1e); 


async Task SaveBitmapToFi1e (StorageFi1e StorageFi1e) 


usi ng 
{ 


(IRandomAccessStream fi1eStream = 

await StorageFi1e.OpenAsync(Fi1 eAccessMode. ReadWrite)) 


BitmapEncoder encoder = 

await BitmapEncoder .CreateAsync(Bi tmapEncoder .PngEncoderld, fi1eStream); 


CHAPTER 14 Bitmaps 


741 


encoder.SetPixelData(Bi tmapPixelFormat. Bgra8 ， BitmapAlphaMode. Premultiplied, 

(ui nt)bi tmap.PixelWidth ， (uint) bitmap.PixelHeight, 

96, 96, pixels); 
await encoder. FlushAsyncO ; 

} 

} 

} 


The MainPage.xaml.es file shown next has several responsibilities. The code in this file saves 
application settings during program suspension and restores them when the program starts up. It 
also saves the current picture and reloads it. This logic makes use of methods in the MainPage.File.es 
file, but of course it must ignore any exceptions that might occur. 

This file is also responsible for handling the SizeChanged event, both for setting the visual state 
used in the XAML file and for setting the imogeScale and imogeOffset fields. Depending on the 
original size of the bitmap, the screen orientation, and the snapped state, the bitmap currently 
serving as the finger-painting canvas might be larger or smaller than the page. It’s always displayed as 
large as possible without aspect ratio distortion, but touch coordinates must be converted to bitmap 
coordinates for drawing on it. 

Project: FingerPaint I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

AppSettings appSettings = new AppSetti ngs() ; 
double imageScale = 1; 

Point imageOffset = new Poi nt() ; 

public MainPage() 

{ 

this. InitializeComponentO; 

SizeChanged += OnMainPageSizeChanged; 

Loaded += OnMainPageLoaded; 

Application. Current.Suspending += OnApplicationSuspending; 

} 


void OnMainPageSi zeChanged(object sender, SizeChangedEventArgs args) 

{ 

VisualStateManager.GoToState(thi s , ApplicationVi ew. Value.ToString(), true) ; 

if (bitmap != null) 

{ 

CalculatelmageScaleAndOffset(); 

} 

} 


void CalculatelmageScaleAndOffset() 


} 


imageScale = Math. Min (thi s. ActualWidth / bitmap.PixelWidth, 

this. ActualHeight / bitmap.PixelHeight); 

imageOffset = new Poi nt( (thi s .ActualWidth - imageScale * bitmap.PixelWidth) / 2 ， 

(thi s .ActualHeight - imageScale * bitmap.PixelHeight) / 2); 
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async void OnMainPageLoaded (obj ect sender, RoutedEventArgs args) 


try 

StorageFolder local Folder = Appli cationData.Current. Local Folder; 

StorageFi 1e storageFile = await localFolder.GetFileAsync("Fi ngerPaint.png") ; 
await LoadBitmapFromFi1e(storageFi1e); 

} 

catch 

{ 

// Ignore any errors 

} 

if (bitmap == null) 

await CreateNewBitmapAndPixelArrayC); 

} 

async void OnApplicationSuspendi ngCobject sender, SuspendingEventArgs args) 

{ 

// Save application settings 
appSettings.Save(); 

// Save current bitmap 

SuspendingDeferral deferral = args.SuspendingOperation.GetDeferral(); 
try 

StorageFol der local Folder = Appli cationData.Current. Local Folder; 

StorageFi 1 e storageFile = await localFolder.CreateFileAsync("Fi ngerPaint.png" , 

CreationCol1isionOption .ReplaceExisting); 

await SaveBitmapToFi1e(storageFi1e); 

} 

catch 

{ 

// Ignore any errors 

} 

deferral.Compl ete(); 


The MainPage.xaml.es file is also responsible for handling the Color and Thickness application 
bar buttons by displaying Popup objects with UserControl derivatives named ColorSettingDiolog and 
ThicknessSetting Dialog. 


Project: FingerPaint I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 


void OnColorAppBarButtonCli ck(object sender, RoutedEventArgs args) 

{ 

DisplayDialog(sender, new ColorSettingDialogO) ; 


CHAPTER 14 Bitmaps 


743 


void OnThicknessAppBarButtonCli ck(object sender, RoutedEventArgs args) 

{ 

Di splayDialogCsender, new ThicknessSettingDialogO) ; 

} 

void DisplayDialog (object sender, FrameworkElement dialog) 

{ 

dialog.DataContext = appSettings; 

Popup popup = new Popup 

{ 

Child = dialog, 

IsLightDismissEnabled = true 


dialog.SizeChanged += (dialogSender, dialogArgs)=> 

{ 

// Get Button location relative to screen 
Button btn = sender as Button ; 

Point pt = btn.TransformToVisual (null) .TransformPoint( 

new Poi nt(btn.ActualWidth / 2, 

btn.Actual Height / 2)); 

popup.HorizontalOffset = Math .Max(24, pt.X - dialog.ActualWidth / 2); 

if (popup.HorizontalOffset + dialog.ActualWidth > this .ActualWidth) 
popup.HorizontalOffset = this .ActualWidth - dialog.ActualWidth; 

popup.HorizontalOffset = Math .Max(0, popup.HorizontalOffset); 

popup.VerticalOffset = this .ActualHeight - dialog.ActualHeight 

- this .BottomAppBar.ActualHeight - 24; 

}； 

popup.Closed += (popupSender, popupArgs)=> 

{ 

this .BottomAppBar.IsOpen = false; 

}； 

popup.IsOpen = true; 



The ThicknessSettingDiolog is definitely the simpler of the two. It simply contains a ListBox with a 
bunch of possible line-thickness values. I wanted powers of 2 — such as 2, 4, 8, 16, 32 — but I also want¬ 
ed values between those as well, so basically the values increase by the cube root of 2 with rounding 
and elimination of redundancy: 

Project: FingerPaint I File: ThicknessSettingDialog.xaml (excerpt) 

<Cri d> 

〈Border Background="Whi te" 

BorderBrush=" Black" 

BorderThi ckness="3" 

Padding="32"> 
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<ListBox SelectedItem="{Bi nding Thickness, Mode=TwoWay} 
Width="150"> 

<x: Doubl e>2</x: Double> 

<x: Doubl e>3</x: Doubl e> 

<x: Doubl e>4</x: Double 〉 

<x: Doubl e>5</x: Double> 

<x: Doubl e>6</x: Double> 

<x: Doubl e>8</x: Double> 

<x: Doubl e>10</x : Double 〉 

<x: Doubl e>13</x : Doubl e> 

<x: Doubl e>16</x : Doubl e> 

<x: Doubl e>20</x : Double> 

<x: Doubl e>25</x : Double> 

<x: Doubl e>32</x: Double> 

<x: Doubl e>40</x : Double 〉 


<ListBox.Foreground 〉 

<SolidColorBrush Color="{Binding Color}" /> 
</ListBox.Foreground 〉 


<ListBox.ItemTemplate> 

<DataTemplate> 

<Grid Height="{Bi nding}" 

Width="120"> 

<Canvas VerticalAli gnment="Center" 

HorizontalAli gnment="Center"> 

<Polyline Points="-36 0 36 0" 

Stroke="{Bi ndi ng RelativeSou rce={RelativeSource TemplatedParent} , 

Path=Fo reground}" 

StrokeThickness="{Bi ndi ng}" 

StrokeStartLi neCap="Round" 

StrokeEndLi neCap="Round" /> 

</Canvas> 

</Gri d> 

</DataTemplate> 

</ListBox.ItemTemplate> 


<ListBox.ItemContainerStyl e> 

<Style TargetType="Li stBoxItem"> 

<Setter Property=" Background" Val ue="Tran sparer)t" /> 

<Setter Property="Templ ate"> 

<Setter.Value> 

<ControlTempi ate TargetType="Li stBoxItem"> 

<Gri d> 

<VisualStateManager.VisualStateGroups> 

<VisualStateGroup x:Name="Sel ectionStates"> 

<VisualState x:Name="Unsel ected"> 

<Storyboard> 

<0bj ectAni mati onllsi ngKeyFrames 

Storyboard.TargetName=" border" 

Storyboard.TargetProperty=" BorderBrush"> 
<DiscreteObjectKeyFrame 

KeyTime="0" 

Val ue="Transparent" /> 
</0bjectAnimationUsingKeyFrames> 
</Storyboard> 

</VisualState> 
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<VisualState x : Name="Sel ected" /> 

<VisualState x: Name="SelectedUnfocused" /> 
<VisualState x : Name="Sel ectedDisabled" /> 

<VisualState x : Name="Sel ectedPointerOver" /> 
<VisualState x: Name=" SelectedPressed" /> 

</VisualStateGroup> 

</VisualStateManager.VisualStateGroups> 


<Border Name="border" 

BorderBrush=" Black" 

BorderThi ckness="l" 

Background="Trans parent" 

Paddi ng="12"> 

<ContentPresenter Content="{Templ ateBinding Content}" /> 


</Border> 

</Grid> 

</ControlTemplate> 

</Setter.Value> 

</Setter> 

</Style> 

</ListBox.ItemContainerStyle> 

</ListBox> 

</Border> 

</Crid> 

Of course, all the "magic” occurs in the templates. (There is nothing in the code-behind file except 
a call to InitiolizeComponent.) The ItemTemplate uses the value in the ListBox as a thickness for an 
actual line, and the Item Con tain erStyl e causes a rectangle to be drawn around the selected value: 
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When Main Page displays this dialog, the DotaContext is set to the AppSettings instance, so the 
value of the Thickness property in that class is updated through the data binding. That value is used in 
all subsequent drawing operations until the next change. 


HSL Color Selection 


You’ve probably seen a few too many color selectors in the book built from sliders that let you pick 
Red, Green, and Blue values. That’s an easy way to pick color because it’s the way that color is defined 
in video displays and in the Windows Runtime. 

However, it's not really an intuitive way to select colors. People seem to prefer a system built 
around values named Hue, Saturation, and Lightness. Hue is basically a color of the rainbow, named 
by Isaac Newton as red, orange, yellow, green, blue, indigo, and violet. Using more "computerish” 
colors, Hue ranges continuously from red, through yellow, green, cyan, blue, magenta, and back to 
red. Notice the three additive primaries (red, green, and blue) and the three subtractive primaries 
(yellow, cyan, and magenta), which are combinations of the pair of additive primaries surrounding 
them. 

The Hue is combined with a Saturation value. When the Saturation is a maximum value, the color is 
most vivid. At a minimum saturation, the color is gray. Then Lightness comes into play. Increasing the 
Lightness washes out the color and eventually turns it white at the maximum value. Decreasing the 
Lightness from its medium value turns the color black. 


Hue-Saturation-Lightness (or HSL) color selection is used in Windows Paint and Microsoft Word, 
where a two-dimensional grid (similar to the XYSlider in Chapter 13) is used for the combination of 
Hue and Saturation and a regular slider is used for Lightness. 

To mimic this type of color selection, I created an HSL structure for representing an HSL color 
value. This structure incorporates conversion routines between RGB and HSL: 


Project: FingerPaint I File: HSL.cs 

public struct HSL 
{ 

public HSL(byte hue, byte saturation, byte lightness) : 

this (360 * hue / 255.0, saturation / 255.0, lightness / 255.0) 

{ 

} 

// Hue from 0 to 360, saturation and lightness from 0 to 1 
public HSL(doubl e hue, double saturation, double lightness) : thi s() 
{ 

this. Hue = hue; 

this■ Saturation = saturation; 

this .Lightness = lightness; 

double chroma = saturation * (1 - Math .Abs(2 * lightness - 1)); 
double h = hue / 60; 
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double x = chroma * (1 - Math .Abs(h % 2 - 1)); 
double r = 0, g = 0, b = 0; 


if (h < 1) 

{ 

r = chroma; 

9 = x; 

} 

else if (h < 2) 

{ 

r = x; 
g = chroma; 

} 

else if (h < 3) 

{ 

g = chroma; 
b = x; 

} 

else if (h < 4) 

{ 

g = x ； 
b = chroma; 

} 

else if (h < 5) 

{ 

r = x; 
b = chroma; 

} 

else 

{ 

r = chroma; 
b = x; 

} 

double m = "lightness - chroma / 2; 

this. Col or = Col or. FromArgb(255, (byte) (255 * 

(byte) (255 * 
(byte) (255 * 


public HSL(Col or color) 

: this() 

{ 

this. Col or = color; 

double r = color.R / 255.0; 

double g = color.G / 255.0; 

double b = color.B / 255.0; 

double max = Math.Max(r, Math .Max(g, b)); 

double min = Math.Min(r, Math .Min(g, b)); 

double chroma = max - min; 

this .Lightness = (max + min) / 2; 

if (chroma != 0) 

{ 

if (r == max) 


， J ) 
))) 
) )) 
m m m 



c c c 
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this. Hue = 60 * (g - b) / chroma; 


else if (g == max) 

this. Hue = 120 + 60 * (b - r) / chroma; 

else 

this. Hue = 240 + 60 * (r - g) / chroma; 

this. Hue = (this. Hue + 360) % 360; 

if (this .Lightness < 0.5) 

this ■Saturation = chroma / (2 * this .Lightness); 

else 

this ■Saturation = chroma / (2 - 2 * this .Lightness); 



public double Hue { private set ; get ; } 
public double Saturation { private set; get ; } 
public double Lightness { private set; get; } 
public Color Color { private set ; get; } 


Notice the two different constructors, one using byte arguments and the other using double 
arguments. For a particular call to an HSL constructor, the C# compiler needs to choose which 
constructor to use, and it will choose the first one only if all the arguments are byte values. There’s no 
such ambiguity with the third constructor, which converts a Color value to HSL. 

I presented an XYSlider control in the previous chapter but indicated that it would be more usable 
if it used Pointer events rather than Manipulation events. Here’s the revised version. Because it’s work¬ 
ing with Pointer events, it needs to keep track of multiple fingers, but it simply averages the positions 
of those fingers to create a composite position. Otherwise, the control is basically the same: 


Project: FingerPaint I File: XYSIider.es (excerpt) 

public cl ass XYSlider : ContentControl 

{ 

ContentPresenter contentPresenter; 

FrameworkElement crossHairPart; 

Dictionary<uint, Poi nt> pointerDictionary = new Dictionary<uint, Poi nt>() ; 


static readonly DependencyProperty valueProperty = 
DependencyProperty .Regi ster("Val ue" , 

typeof (Point) , typeof (XYS1 i der) , 

new PropertyMetadata(new Poi nt() , OnValueChanged)); 

public event EventHandler<Poi nt> ValueChanged; 

public XYS1ider() 

{ 

this.DefaultStyleKey = typeof (XYS1 i der) ; 
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} 


public static DependencyProperty ValueProperty 

{ 

get { return valueProperty; } 

} 

public Point Value 

{ 

set { SetValue(ValueProperty, value); } 

get { return (Poi nt)GetValue(ValueProperty); } 

} 

protected override void OnApplyTemplate() 

{ 

// Detach event handlers 
if (contentPresenter != null) 

{ 

contentPresenter.PointerPressed -= OnContentPresenterPointerPressed; 
contentPresenter.PointerMoved -= OnContentPresenterPointerMoved; 
contentPresenter.PointerReleased -= OnContentPresenterPointerReleased; 
contentPresenter.PointerCaptureLost -= OnContentPresenterPointerReleased; 
contentPresenter.SizeChanged -= OnContentPresenterSizeChanged; 

} 

// Get new parts 

crossHairPart = GetTemplateChi1 d("CrossHairPart") as FrameworkElement ; 
contentPresenter = GetTemplateChiId ("ContentPresenterPart") as ContentPresenter; 

// Attach event handlers 
if (contentPresenter != null) 

{ 

contentPresenter.PointerPressed += OnContentPresenterPointerPressed; 
contentPresenter.PointerMoved += OnContentPresenterPointerMoved; 
contentPresenter.PointerReleased += OnContentPresenterPointerReleased; 
contentPresenter.PointerCaptureLost += OnContentPresenterPointerReleased; 
contentPresenter.SizeChanged += OnContentPresenterSizeChanged; 

} 

// Make cross-hair transparent to touch 
if (crossHairPart != null) 

{ 

crossHairPart.IsHitTestVisible = false; 

} 

base ■OnApplyTemplate(); 

} 

void OnContentPresenterPointerPressed (object sender, PointerRoutedEventArgs args) 

{ 

uint id = args.Pointer.Pointerld; 

Point point = args.GetCurrentPoint(contentPresenter).Position; 
pointerDictionary.Add(id, point); 
contentPresenter.CapturePointer(args.Pointer); 

RecalculateValue(); 
args.Handled = true; 
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} 


void OnContentPresenterPointerMoved (object sender, PointerRoutedEventArgs args) 

{ 

uint id = args.Pointer.Pointerld; 

Point point = args.GetCurrentPoint(contentPresenter).Position; 

if (pointerDictionary.ContainsKey(id)) 

{ 

pointerDictionary[id] = point; 

RecalculateValue(); 
args.Handled = true ; 

} 


void OnContentPresenterPointerRel eased(object sender, PointerRoutedEventArgs args) 

{ 

uint id = args■Pointer.Poi nterld; 

if (pointerDictionary.ContainsKey(id)) 

{ 

pointerDictionary.Remove(id); 

RecalculateValue(); 
args.Handled = true ; 

} 


void OnContentPresenterSizeChanged (object sender, SizeChangedEventArgs args) 
{ 

SetCrossHair(); 

} 


void RecalculateValue() 

{ 

if (pointerDictionary.Values.Count > 0) 

{ 

Point accumPoint = new Poi nt() ; 

// Average all the current touch points 
foreach (Poi nt point in pointerDictionary.Values) 
{ 

accumPoint.X += point.X; 
accumPoint.Y += point.Y; 

} 

accumPoint.X /= pointerDictionary.Values.Count; 
accumPoint.Y /= pointerDictionary.Values.Count; 


} 


RecalculateValue(accumPoint); 

} 


void RecalculateValue (Point absolutePoint) 

{ 

double x = Math .Max(0, Math .Min(l, absolutePoint.X / contentPresenter.ActualWidth)); 
double y = Math.Max(0, Math .Min(l, absolutePoint.Y / contentPresenter.ActualHeight)); 
this. Value = new Point(x, y); 


} 
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void SetCrossHair() 

{ 

if (contentPresenter != null && crossHairPart != null) 

{ 

Canvas .SetLeft(crossHairPart, this .Value.X * contentPresenter.ActualWidth); 
Canvas .SetTop(crossHairPart, this .Value.Y * contentPresenter.ActualHeight); 



static void OnValueChanged (DependencyObject obj, DependencyPropertyChangedEventArgs args) 

{ 

(obj as XYSTider). SetCrossHair(); 

(obj as XYS1ider) .OnValueChanged((Point)args.NewValue); 

} 

protected void OnValueChanged(Poi nt value) 

{ 

if (ValueChanged != null) 

ValueChanged(thi s , value); 

} 

} 


The next step is to build an HsIColorSelector control. This is derived from User Control and 
instantiates an XYSlider, Slider, and TextBlock in the XAML file. The Resources section defines 
ControlTemplate objects for the XYSlider and Slider. The XYSlider template is considerably simplified 
from what I showed for the corresponding control in Chapter 13 because I knew exactly the visuals I 
wanted and didn’t add anything else. 


Project: FingerPaint | File: HsIColorSelector.xaml (excerpt) 

<UserControl … > 

<UserControl.Resources 〉 

<ControlTempi ate x : Key="xySl iderTemplate" TargetType="l ocal : XYSlider% 
<Border> 

<Grid> 

<ContentPresenter Name="Content PresenterPart" 

Content="{TemplateBinding Content}" /> 

<Canvas> 

<Path Name="CrossHai rPart" 

Fi "11 =" {Tempi ateBi ndi ng Foreground}" 

Data="M 0 6 L -3 24 3 24 Z 

M 0 -6 L -3 -24 3 -24 Z 
M 6 0 L 24 -3 24 3 Z 


M -6 0 L -24-2 -24 


</Canvas> 
</Gri d> 
</Border> 

</ControlTemplate> 


〈ControlTempi ate x: Key="sl iderTemplate" TargetType="Sl ider"> 
<Gri d> 

<Grid Name="Hori zontalTemplate" 
Background="Transparent" 

Height="48"> 

<Grid.ColumnDefinitions> 

<ColumnDefinition Width="*" /> 
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<ColumnDefinition Wi dth="Auto" /> 

<ColumnDefinition Wi dth="Auto" /> 

</Grid.ColumnDefinitions> 

〈Rectangle Name="Hori zontalTrackRect" 

Grid.Column="0" 

Grid.ColumnSpan="3" 

Fi1 l="{TemplateBinding Background}" 
Height="12" 

VerticalA1i gnment="Top" /> 

<Thumb Name="Hori zontalThumb" 

Grid.Column="l" 

DataContext=" {TempiateBinding Value}"> 

<Thumb.Template 〉 

<ControlTempi ate TargetType="Thumb"> 

<Path Fi11=" {TempiateBinding Foreground}" 
Data="M 0 24 L -3 48 3 48 Z" /> 
〈 /ControlTempiate> 

</Thumb.Tempi ate> 

</Thumb> 


〈Rectangle Name="Hori zontalDecreaseRect" 
Grid.Column="2" 
Fill="Transparent" /> 

</Crid> 


<Grid Name="Verti calTemplate" 
Background="Transparent" 
Width="48"> 

<Grid.RowDefinitions> 

<RowDefinition Height="*" /> 

< RowDefinition Hei ght="Auto" /> 
〈RowDefinition Height="Auto" /> 
</Grid.RowDefiniti ons> 


〈Rectangle Name="Verti calTrackRect" 

Grid.Row="0" 

Grid.RowSpan="3" 

Fi11 =" {TempiateBinding Background}" 
Width="12" 

HorizontalA1i gnment="Left" /> 

〈Thumb Name="Verti calThumb" 

Grid•Row="l" 

DataContext=" {TempiateBinding Value}"> 

<Thumb.Tempiate> 

〈 ControlTemp"!ate TargetType="Thumb"> 

<Path Fi11 =" {T emplateBinding Foreground}" 
Data="M 24 0 L 48 -3 48 3 Z" /> 
</ControlTemplate> 

</Thumb.Tempiate> 

</Thumb> 


〈Rectangle Name="Verti calDecreaseRect" 
Grid.Row="2" 
Fill="Transparent" /> 
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</Gri d> 

</Gri d> 

〈 /ControlTempiate> 
</UserControl.Resources 〉 


<Gri d> 

<Grid.RowDefinitions> 

<RowDefinition Hei ght="Auto" /> 

〈RowDefinition Height="Auto" /> 

<RowDefinition Hei ght="Auto" /> 

</Grid.RowDefinitions> 

〈 local : XYS1ider x : Name="xySl ider" 

Grid.Row="0" 

Tempi at e="{StaticResource xySliderTemplate}" 

Val ueChanged="OnXYSl iderValueChanged"> 

<Image Name="hslmage" 

Stretch="None" /> 

</local : XYS1ider> 

<S1ider Name="sl ider" 

Grid.Row="l" 

On' entati on="Hori zontal " 

Tempi ate="{StaticResource siiderTemplate}" 

Width=__256 n 
Margin="0 12" 

ValueChanged="OnSl iderValueChanged"> 

<S1ider.Background 〉 

<LinearGradientBrush StartPoi nt="0 0" EndPoint="l 0"> 

<GradientStop 0ffset="0" Color="Black" /> 

<GradientStop x : Name="sl iderGradientStop" 0ffset="0. 5" /> 
<GradientStop 0ffset="l" Color="Whi te" /> 

</LinearGradientBrush> 

</Slider.Background 〉 

</Slider> 

<TextBlock Name="txtbl k" 

Grid.Row="2" 

HorizontalA1i gnment="Center" 

TextAli gnment="Center" 

FontSize="24" /> 

</Gri d> 

</UserControl > 


Notice that the ControlTemplote for the Slider basically colors the control with its Background 
property. This Background property is defined on the Slider itself toward the bottom of the XAML file. 
It’s a LineorGrodientBrush that ranges from black to white with a color in the center settable from the 
code-behind file. That color is based on the combination of Hue and Saturation the user selects from 
the XYSlider. 
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The code-behind file defines a Dependency Property named Color of type Color. Obviously, as a 
public property to be used in bindings, this Color property makes much more sense than a public 
property of type HSL. The Loaded handler is responsible for creating a bitmap for the main 
Hue-Saturation grid. It uses the HSL structure to convert from HSL (with an average Lightness value) 
to obtain RGB values for the bitmap pixels. 


Project: FingerPaint I File: HslColorSelector.xaml.es (excerpt) 

public partial class HslColorSelector : UserControl 

{ 

bool doNotSetSliders = false; 


static readonly DependencyProperty colorProperty = 
DependencyProperty .Regi ster("Color" , 
typeof (Col or) , 
typeof (HslColorSelector) , 

new PropertyMetadata (new Color() , OnColorChanged)); 

public event EventHandler<Color> ColorChanged; 

public HslColorSelector() 

{ 

this. InitializeComponent(); 

Loaded += OnLoaded; 


async void OnLoaded(object sender, RoutedEventArgs args) 

{ 

// Build bitmap for hue/saturation grid 
WriteableBitmap bitmap = new WriteableBi tmap(256, 256); 
byte[] pixels = new byte [4 * 256 * 256]; 
int index = 0; 


for (int y = 0; y < 256; y++) 

for (int x = 0; x < 256; x++) 

{ 

HSL hsl = new HSL((byte)x, (byte) (255 - y), (byte)128) ; 
Color clr = hsl.Color; 



pixels[index++] 
pixels[index++] 
pixels[index++] 
pixels[index++] 


clr.B; 
clr.G; 
clr.R; 
clr.A; 


using (Stream pi xel Stream = bitmap. Pi xel Buffer .AsStreamO) 

{ 

await pixelStream.WriteAsync(pixels, 0, pixels■Length); 

} 

bitmap.Invalidate(); 
hslmage.Source = bitmap; 
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public static DependencyProperty ColorProperty 


get { return colorProperty; } 

} 

public Color Color 

{ 

set { SetValue(ColorProperty, value); } 

get { return (Color)GetValue(ColorProperty); } 

} 

// Event handlers for sliders 

void OnXYSliderValueChanged(object sender, Point point) 

{ 

HSL hsl = new HSLC360 * point.X, 1 - point.Y ， 0.5); 
sliderGradientStop.Color = hsl.Color; 

SetColorFromSliders(); 

} 

void OnSliderValueChanged(object sender, RangeBaseValueChangedEventArgs args) 

{ 

SetColorFromSliders(); 

} 

void SetColorFromSliders() 

{ 

Point point = xySlider.Value; 
double value = siider.Value; 

HSL hsl = new HSL (360 * point.X, 1 - point.Y ， value / 100); 

doNotSetSliders = true; 
this. Col or = hsl.Color; 
doNotSetSliders = false; 

} 

// Color property-changed handlers 

static void OnColorChanged(DependencyObject obj ， DependencyPropertyChangedEventArgs args) 

{ 

(obj as HslColo 「 Selector) .0nColorChanged((Co1or)args.NewValue); 

} 

protected void OnColorChanged (Col or color) 

{ 

HSL hsl = new HSL(color); 

if (!doNotSetSliders) 

{ 

xySlider.Value = new Poi nt(hsl.Hue / 360 ， 1 - hsl.Saturation); 
slider.Value = 100 * hsl.Lightness; 

} 
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txtblk.Text = String. Format("RGB = ({0 }， {1 }， {2 })"， 

this. Color.R, this .Color.G ， this. Color.B); 

if (ColorChanged != null) 

ColorChanged(thi s , color); 

} 

} 

When a new Color property is set from outside the file, the OnColorChanged handler responds 
by setting the XYSlider and Slider values as well as using the TextBlock to display the RGB color 
value. When the user manipulates the XYSlider and Slider values, a new Color property is set and 
OnColorChanged is called. Normally, recursive calls to property-changed handlers are OK, but not in 
this case because a round-trip conversion — RGB to HSL to RGB — doesn’t result in exactly the same 
value. That’s the reason for the Boolean doNotSetSliders field when the Color property is changed 
from user input. 

Finally, a ColorSettingDiolog incorporates the HsIColorSelector: 

Project: FingerPaint | File: ColorSettingDialog.xaml (excerpt) 

<Gri d> 

<Border Background="Whi te" 

BorderBrush=" Black" 

BorderThickness="3" 

Padding="32"> 

<StackPanel> 

<Path Data="M 0 50 C 80 0 160 100 256 0" 

StrokeStartLi neCap="Round" 

StrokeEndLi neCap="Round" 

StrokeThickness="{Bi nding Thickness}" 

Margin="0 12"> 

<Path.Stroke> 

<SolidColorBrush Color="{Bi nding Color}" /> 

</Path.Stroke> 

</Path> 


<local : HslColo「Selector x:Name="hslColorSel ector" 


</StackPanel> 

</Border> 

</Crid> 


Foreground:" Black" 

Color="{Binding Path=Color, Mode=TwoWay}" /> 
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For a preview, the control displays a squiggle based on the current thickness and color: 



When you use Finger Paint on anything other than a very high resolution display, you’ll probably 
notice that the drawing is a little grainier than the earlier FingerPaint programs from Chapter 13. 
There’s a very good reason for this: When you render graphical objects with Line, Polyline, and 
Path, you get antialiasing. The boundary lines are a combination of the fill color and the background 
color, and perceptually the lines are smoother. But there is no antialiasing implemented in the 
Petzold.Windows8.VectorDrawing library. Either a pixel is colored, or it is not. 


Reverse Painting 


I once saw a little movie of someone painting over a large colorful mural with white paint and a roller, 
except that the movie was run in reverse so that it seemed as if the mural was being magically created 
by painting with the roller over a white surface. 

A similar technique is illustrated in the ReversePaint program. The XAML file accesses a bitmap on 
my website and defines another Image element that lies on top: 


Project: ReversePaint I File: MainPage.xaml (excerpt) 

<Crid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Image Sou rce="http: //www.charlespetzold.com/pw6/PetzoldJersey.jpg" /> 
<Image Name="whi telmage" /> 

</Grid> 


The bitmap for the second Image element is created in the Loaded handler to be the same size 
as the downloaded bitmap and all white. Like FingerPaint, there’s a ColculotelmogeScaleAndOffset 
method that calculates factors for scaling pointer input to the bitmap. To streamline the presentation 
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of the code, I’ve removed a lot of comments from the pointer event handlers, but you’ve seen the 
logic before. The OnPointerMoved method calls a simplified form of RenderOnBitmop with two points, 
a fixed line thickness, and a Color value representing transparency: 


Project: ReversePaint I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

Dicti onary<ui nt , Poi nt> pointerDictionary = new Dicti onary<ui nt , Poi nt>() ; 
Li st<double> xCol1ection = new Li st<doubl e>() ; 


WriteableBitmap bitmap; 
byte[] pixels; 

Stream pixel Stream; 

Point imageOffset = new Poi nt(); 
double imageScale = 1; 


public MainPage() 

{ 

this. Ini tializeComponent(); 

SizeChanged += OnMainPageSizeChanged; 
Loaded += OnMainPageLoaded; 


void OnMainPageSi zeChanged(object sender, SizeChangedEventArgs args) 

{ 

if (bitmap != null) 

CalculatelmageScaleAndOffset(); 

} 

async void OnMainPageLoaded (object sender, RoutedEventArgs args) 

{ 

bitmap = new WriteableBitmap (320, 400); 

pixels = new byte [4 * bitmap.PixelWidth * bitmap.PixelHeight]; 


// Initialize pixels to white 

for (i nt index = 0; index < pixels■Length; index++) 
pixels[index] = OxFF; 

pixel Stream = bitmap.PixelBuffer.AsStream(); 

await pixelStream.WriteAsyncCpixels, 0, pi xel s.Length); 

bitmap.Invalidate(); 


// Set to Image element 
whitelmage■Source = bitmap; 

CalculatelmageScaleAndOffset(); 


void CalculatelmageScaleAndOffset() 

{ 

imageScale = Math .Mi n(thi s .ActualWidth / bitmap.Pi xelWidth, 

this .ActualHeight / bitmap.PixelHeight); 
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} 


imageOffset = new Poi nt((thi s .ActualWidth - imageScale * bitmap.PixelWidth) / 2 ， 

(this .Actual Height - imageScale * bitmap.Pixel Height) / 2); 


protected override void OnPointerPressed(Poi nterRoutedEventArgs args) 

{ 

uint id = args.Pointer.Pointerld; 

Point point = args.GetCurrentPoint (this) .Position; 
pointerDictionary.Add(id, point); 

CapturePointer(args.Pointer); 
base. OnPointerPressed(args); 


protected override void OnPointerMoved(Poi nterRoutedEventArgs args) 

{ 

uint id = args.Poi nter. Pointerld; 

Point point = args.GetCurrentPoint (this) .Position; 

if (poi nterDi cti onary .Contai nsl<ey(i d)) 

{ 

Point previousPoint = pointerDictionary[id]; 

// Render the line 

RenderOnBitmapCpreviousPoint, point, 12， new ColorO) ; 
pointerDictionary[id] = point; 

} 

base .OnPointerMoved(args); 


protected override void OnPointerReleased(Poi nterRoutedEventArgs args) 

{ 

uint id = args.Pointer.Pointerld; 

if (pointerDictionary.ContainsKey(id)) 
pointerDictionary.Remove(id); 

base. OnPointerReleased(args); 


protected override void OnPointerCaptureLost(Poi nterRoutedEventArgs args) 

{ 

uint id = args■Pointer.Pointerld; 

if (pointerDictionary.ContainsKey(id)) 
pointerDictionary.Remove(id); 

base. OnPointerCaptureLost(args); 

} 

void RenderOnBitmap(Poi nt pointl ， Point point2, double radius, Color color) 

{ 

bool bitmapNeedsUpdate = false; 
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// Adjust the points for any bitmap scaling 
Point centerl = SealeToBitmapCpointl); 

Point center2 = SealeToBitmapCpoint2); 


// Create object to render the line 

RoundCappedLine line = new RoundCappedLi ne(centerl, center2, radius); 

// Find the minimum and maximum vertical coordinates 
int yMin = (int) Math .Min(centerl.Y - radius, center2.Y - radius); 
int yMax = (i nt)Math .Max(centerl.Y + radius, center2.Y + radius); 

yMin = Math. Max(0 ， Math .Min(bitmap.PixelHeight ， yMin)); 
yMax = Math. Max(0, Math. Min(bitmap.PixelHeight, yMax)); 


// Loop through all the y coordinates that contain part of the segment 
for (int y = yMin; y < yMax; y++) 

{ 

// Get the range of x coordinates in the segment 
xCollection.Clear(); 

1ine.GetAllX(y, xCollection); 

if (xCol1ection.Count == 2) 

{ 

// Find the minimum and maximum horizontal coordinates 

int xMin = (i nt) (Math .Min(xCol1ection[0], xCollection[l]) + 0.5f); 

int xMax = (int) (Math. Max(xCollection[0], xCollection[l]) + 0.5f); 

xMin = Math .Max(0, Math .Min(bitmap.PixelWidth, xMin)); 
xMax = Math .Max(0, Math .Min(bitmap.PixelWidth, xMax)); 


// Loop through the X values 
for (int x = xMin; x < xMax; x++) 
{ 


// Set the pixel 
int index = 4 * (y ' 
pixels [index + 0]= 
pixel s [i ndex + 1]= 
pixels[index + 2]= 
pixels[index + 3]= 
bitmapNeedsUpdate = 


r bitmap.PixelWidth + x); 
color.B 
color.G 
color.R 
color.A 
true ; 


} 

// Update bitmap 
if (bitmapNeedsUpdate) 
{ 


// Find the starting index and number of pixels 

int start = 4 * yMin * bitmap.PixelWidth; 

int count = 4 * (yMax - yMin) * bitmap.PixelWidth; 


pixelStream.Seek(start, SeekOrigin .Begin); 


CHAPTER 14 Bitmaps 


761 



pixelStream.Write(pixels, start, count); 
bitmap.Invalidate(); 



} 


Point ScaleToBitmap(Poi nt pt) 


return new Poi nt((pt.X - imageOffset.X) 

(pt.Y - imageOffset.Y) 


} 


/ imageScale, 

/ imageScale); 


The RenderOnBitmap method is simpler than the one in FingerPaint because it’s only dealing with 
a constant thickness and uses RoundCoppedLine uniformly. Here’s the result after "painting” the white 
bitmap with a few strokes of transparent pixels: 



Notice that the PointerMoved method calls RenderOnBitmap like this: 

RenderOnBitmap(previousPoint, point, 12 ， new Col or()); 

The Color constructor creates a Color value with the A, R, G, and B properties all set to zero, a 
color sometimes known as "transparent black .〃 For putting colors in a WriteobleBitmop, this Color 
constructor is much better than the static Colors.Transparent property. Colors.Transparent returns a 
Color value with an A property equal to zero but R, G, B set to 255. This color is sometimes referred to 
as "transparent white,” but it’s not a premultiplied-alpha transparent color! For WriteobleBitmap you 
need premultiplied-alpha colors, and that means that none of the R, G, and B properties should be 
greater than A. 
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Accessing the Pictures Library 

It’s possible for an application to access the Pictures library directly and to enumerate all the 
subfolders and files in those folders. The program can display those files on the screen most efficiently 
as thumbnails but can then access the actual bitmaps. 

This is demonstrated in the PhotoScatter program. This program constructs a ListBox at the left 
of the page showing the directory structure of the Pictures library. Select a folder and the program 
displays the contents of that folder as thumbnails. You can use your fingers to move, scale, and rotate 
the images, at which time the real file is loaded so that it can be enlarged with more resolution. 

Here’s what the program looks like. You might recognize some of the 200-odd images currently 
stored in my Screenshots folder: 



I wanted each of the items displayed here to be independently manipulable and to handle 
its own manipulation. To do that, I created a general-purpose ContentContro! derivative 
named MonipulobleContentControl. That control uses a somewhat fancier version of the 
Manipulation Manager class I presented in Chapter 13: 


Project: PhotoScatter | File: ManipulationManager.es 

public cl ass ManipulationManager 
{ 

TransformGroup xformGroup; 

MatrixTransform matrixXform; 

CompositeTransform compositeXform; 

public Mani pul ati onManager() : this (new Composi teTransformO) 
{ 

} 
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public ManipulationManager (CompositeTransform initialTransform) 

{ 

xformGroup = new TransformGroupO ; 
matrixXform = new MatrixTransform() ; 
xformGroup.Chi 1dren.Add(matrixXform); 
compositeXform = initialTransform; 
xformGroup.Chi 1dren.Add(compositeXform); 
this. Matrix = xformGroup.Value; 

} 

public Matrix Matrix { private set ; get; } 

public void AccumulateDel ta(Poi nt position, ManipulationDelta delta) 

{ 

matrixXform.Matrix = xformGroup.Value; 

Point center = matrixXform.TransformPoint(position); 
compositeXform.CenterX = center.X; 
compositeXform.CenterY = center.Y; 
compositeXform.TranslateX = delta.Trans1ation.X; 
compositeXform.TranslateY = delta.Translation.Y; 
compositeXform.SealeX = delta.Scale; 
compositeXform.SealeY = delta.Scale; 
compositeXform.Rotation = delta.Rotation; 
this. Matrix = xformGroup.Value; 



The only additional feature is a constructor that lets the orientation of the item be initialized with a 
CompositeTronsform object that is then used within the class. 


To create the ManipulableContentControl class, I created a new item in Visual Studio of type User 
Control. In both the XAML file and the code-behind file I then changed User Control to ContentCoritrol. 
In a User Control derivative, normally the XAML file defines the content of the control. In this XAML file 
the content is left undefined but the RenderTronsform is set to a MatrixTransform that is set from the 
code-behind file based on a Manipulation Manager instance. 


Project: PhotoScatter | File: ManipulableContentControl.xaml 
<ContentControl 

x:Cl ass=" PhotoScatter.ManipulableContentControl" 

xml ns="http: //schemas.microsoft.com/winfx/2006/xaml/presentation" 

xml ns : x="http: //schemas.microsoft.com/winfx/2006/xaml" 

xml ns : 1 ocal="usi ng : PhotoScatter”> 


<ContentControl.RenderTransform> 

<MatrixTransform x : Name="matri xXform" /> 
</ContentControl.RenderTransform> 
</ContentControl > 
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Here’s the code-behind file. Notice the constructor, which takes a CompositeTransform that it uses 
to create a Manipulation Manager object: 


Project: PhotoScatter | File: ManipulableContentControl.xaml.es (excerpt) 

public sealed partial class ManipulableContentControl : ContentControl 

{ 

static int zlndex; 

ManipulationManager manipulationManager; 

public Mani pulableContentControl (CompositeTransform initialTransform) 

{ 

this. InitializeComponent(); 

// Create the Manipulati onManager and set MatrixTransform from it 
manipulati onManager = new ManipulationManager(i nitialTransform); 
mat rixXfo rm.Mat rix = manipulationManager.Matrix; 

thi s. ManipulationMode = ManipulationModes. Al1 & 

〜 ManipulationModes .TranslateRailsX & 

〜 ManipulationModes .TranslateRai 1 sY; 

} 

protected override void OnManipulationStarting (ManipulationStartingRoutedEventArgs args) 

{ 

Canvas .SetZIndex(thi s , zlndex += 1); 
base. OnManipulationStarting(args); 

} 

protected override void OnManipulationDel ta(Mani pulationDeltaRoutedEventArgs args) 

{ 

manipulationManager.AccumulateDelta(args.Position, args.Delta); 
mat rixXfo rm.Mat rix = manipulationManager.Matrix; 
base ■OnManipulationDel ta(args); 


Notice also that the class maintains a static zlndex property that is incremented and used to bring the 
touched item to the top of the pile as soon as the manipulation begins. 


Normally, a directory structure is displayed using a control named TreeView or something similar 
that provides visual indentation and an interface to expand and close up nodes of the tree. The 
Windows Runtime doesn’t have a TreeView (yet), so I decided to use a plain old List Box instead. There 
is no expanding and closing of nodes, but there is indentation. 

The items in the ListBox are of type Folder Item: 


Project: PhotoScatter | File: Folderltem.es 

public cl ass Folderltem 

{ 

public StorageFolder StorageFolder { set; get ; } 
public int Level { set; get ; } 
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public string Indent 

{ 

get { return new string('\xOOAO' , this .Level * 4); } 

} 

public Grid DisplayGrid { set ; get ; } 


Each Folderltem object represents a folder. The name of that folder is obtained from the 
StorogeFolder object, the nesting level is set by code to the Level property, and the Indent property 
uses that value to construct a string of four blanks for each level. 

Folderltem also defines a Display Grid property of type Grid. This Grid object is set the first time the 
user selects that particular folder, and it is filled with a bunch of ManipulableContentControl objects 
corresponding to the images in that folder. Retaining this Grid and everything in it avoids having the 
program re-enumerate the contents of each folder if the user skips around among them. (However, 
the program doesn't install a file watcher, so if items are later added to a folder, the program doesn't 
know about them.) 

The ItemTemplate for the List Box is defined in MainPage.xaml and references properties in 
Folderltem: 

Project: PhotoScatter | File: MainPage.xaml (excerpt) 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

<Grid.ColumnDefinitions> 

<ColumnDefinition Wi dth="Auto" /> 

<ColumnDefinition Width="*" /> 

</Grid.ColumnDefiniti ons> 

<ListBox Name="fol derListBox" 

Grid.Column="0" 

Selecti onChanged="OnFol derListBoxSelectionChanged"> 

<ListBox.ItemTemplate> 

<DataTemplate> 

<ContentControl FontSi ze="24"> 

<StackPanel Orientati on="Hori zontal"> 

〈TextBlock Text="{Binding Indent}" /> 

〈TextBlock Text="&#xE188 ;" 

FontFamily="Segoe UI Symbol" /> 

<TextBlock Text="{Binding StorageFolder .Name}" /> 

</StackPanel> 

</ContentControl > 

</DataTemplate> 

</ListBox.ItemTemplate> 

</ListBox> 

<Border Name="di splayBorder" 

Grid.Col umn="l" /> 

</Grid> 
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Notice the 0xE188 codepoint in the Segoe Ul Symbol font for displaying a little folder icon. That’s 
preceded with the Indent string and followed by the Nome property of the StorogeFolder object in 
Folderltem. 

The PhotoScatter program requires permission to access the Pictures library in the Capabilities 
section of Package.appxmanifest because during the Loaded event it obtains the complete directory 
tree by recursive calls to the GetFoldersAsync method of StorogeFolder, in the process creating the 
Folderltem objects for the ListBox. 

Project: PhotoScatter | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 


public MainPage() 

{ 

this .InitializeComponent(); 
Loaded += OnMainPageLoaded; 


void OnMai nPageLoaded(object sender, RoutedEventArgs args) 

{ 

StorageFolder storageFolder = KnownFolders .PicturesLibrary; 

BuildFolderListBox(storageFolder, 0); 
folderListBox.Selectedlndex = 0; 

} 

async void Bui IdFolderListBox (StorageFolder parentStorageFolder, int level) 
{ 

Folderltem folderltem = new Folderltem 
{ 

StorageFolder = parentStorageFolder, 

Level = level 

}； 

folderListBox.Items.Add(folderltem); 

IReadOnlyList<StorageFolder> StorageFolders = 

await parentStorageFolder.GetFoldersAsyncC); 

foreach (StorageFolder StorageFolder in storageFolders) 

Bui IdFolderListBox(StorageFolder, level + 1); 

} 


The Loaded handler concludes by setting the Selectedlndex of the ListBox to 0, which selects the 
first item, which is the Pictures folder itself. This triggers a call to the SelectionChongecJ handler, 
which uses the GetFilesAsync method of StorageFolder to obtain all the files in that folder. But for 
each StorageFile, the method calls GetThumbnailAsync to obtain the file’s thumbnail image. (Loading 
thumbnails is much preferable to loading the actual images, which could take quite some time and 
consume a lot of memory.) A call to a method in Mo in Page named LoadBitmopAsync (which 111 
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describe shortly) creates an Image element and a MonipulableContentControl for displaying that 
thumbnail: 


Project: PhotoScatter | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

Random rand = new RandomO; 

async void OnFolderListBoxSelectionChanged (object sender, SelectionChangedEventArgs args) 

{ 

Folderltem folderltem = (sender as Li stBox) .Selectedltem as Folderltem; 

if (folderltem == null) 

{ 

displayBorder.Chi Id = null; 
return ; 

} 

if (folderltem.DisplayGrid != null) 

{ 

displayBorder.Chi Id = folderltem.DisplayGrid; 
return ; 

} 

Gri d di spl ayGri d = new Gri d(); 

folderltem.DisplayGrid = displayGrid; 

displayBorder.Child = displayGrid; 


StorageFolder storageFolder = folderltem.StorageFolder; 

IReadOnlyList<StorageFi1 e> storageFi1es = await storageFolder.GetFilesAsync(); 

foreach (StorageFi1e storageFi1e in storageFi1es) 

{ 

StorageltemThumbnai1 thumbnail = 

await storageFile.GetThumbnai1 Async(Thumbnai 1 Mode. Singleltem); 
BitmapSource bitmap = await LoadBitmapAsync(thumbnai1); 

if (bitmap == null) 
continue ; 

// Create new Image element to display the thumbnail 
Image image = new Image 
{ 

Source = bitmap, 

Stretch = Stretch. None, 

Tag = ImageType .Thumbnai1 

}； 


// Create an initial CompositeTransform for the itern 
CompositeTransform xform = new CompositeTransform() ; 

xform.TranslateX = (displayBorder.ActualWidth - bitmap.PixelWidth) / 2; 
xform.T ranslateY = (displayBorder.ActualHeight - bitmap.Pixel Height) / 2; 
xform.TranslateX += 256 * (0.5 - rand.NextDouble()); 
xform.TranslateY += 256 * (0.5 - rand.NextDouble()); 
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// Create the ManipulableContentControl for the Image 

ManipulableContentControl manipulableControl = new ManipulableContentControl (xform) 


Content = image, 

Tag = storageFile 

}； 

mani pul abl eControl .Mani pulationStarted += OnManipulableControlManipulationStarted; 
// Put it in the Grid 

displayGrid.Children.Add(manipulableControl); 



Because of the await operators on GetThumbnoilAsync and LoadBitmopAsync, these BitmopSource 
objects, Image elements, and ManipulobleContentControl instances are created sequentially, and 
each is displayed as it’s created, which provides an entertaining show as the images are progressively 
stacked in a big, slightly random pile. The other option is to let them all go at the same time, but in 
most cases that would result in creating many more threads than processors to handle them. 

The SelectionChonged handler for the List Box is executed only once for each folder. The Tog 
property of the ManipulobleContentControl is set to the Storage File object associated with each item. 
This is later used to load the actual bitmap (if necessary). Also notice that the Tag property of each 
Image element is set to ImageType.Thumbnail. That's a member of the following enumeration: 


Project: PhotoScatter | File: ImageType.cs (excerpt) 

public enum ImageType 
{ 

Thumbnail, 

Full, 

Transitioning 

} 

That Tog property will change as the user begins manipulating a particular item. Although the 
ManipulobleContentControl handles the Manipulation events necessary to allow the item to be 
moved, scaled, and rotated, a handler for the MonipulotionStartecJ event is also attached by that 
SelectionChonged handler. This handler is responsible for replacing the thumbnail with the actual 
bitmap: 


Project: PhotoScatter | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 
{ 

async void OnManipulableControlManipulationStarted (object sender, 

ManipulationStartedRoutedEventArgs args) 

{ 

ManipulableContentControl manipulableControl = sender as ManipulableContentControl ; 
Image image = manipulableControl.Content as Image; 
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if C(ImageType) image.Tag == ImageType. Thumbnail) 

{ 

// Set tag to transitioning 
image.Tag = ImageType. Transitioning; 

// Load the actual bitmap file 

StorageFi1e storageFile = manipulableControl.Tag as StorageFile; 

BitmapSource newBitmap = await LoadBitmapAsync(storageFi1e); 

// This is the case for a file that BitmapDecoder can't handle 
if (newBitmap != null) 

{ 

// Get the thumbnail from the Image element 
BitmapSource oldBitmap = image.Source as BitmapSource ; 

// Find a SealeTransform between old and new 
double scale = 1; 

if (oldBitmap.PixelWidth > oldBitmap.Pixel Height) 

scale = (double)ol dBitmap.PixelWidth / newBitmap.Pixel Width; 

else 

scale = (double)ol dBitmap.Pixel Height / newBitmap.Pixel Height; 

// Set properties on the Image element 
image.Source = newBitmap; 
image.RenderTransform = new SealeTransform 
{ 

ScaleX = scale, 

ScaleY = scale, 

}； 

} 

image.Tag = ImageType ■Full; 

} 

} 

} 


The replacement of the thumbnail by the bitmap is perhaps the trickiest part of the program. 
Because the ManipulotionStorted handler contains asynchronous calls, it could be processing 
overlapping events from several items if the user is manipulating more than one simultaneously. The 
main logic takes place only if the Tag property of the Image is ImogeTypeJhumbnail. The Tog is then 
set to ImageTypeJransitioning (not strictly necessary but it was helpful for debugging), and a call to 
LoadBitmapAsync obtains that image. When it finally replaces the thumbnail, the Tag property of the 
Image element is set to ImageType.Full. 

I wanted the process to be as visually seamless as I could manage, and hence the routine calculates 
scaling factors that convert the size of the actual bitmap to the size of the thumbnail. The size and 
orientation of the item doesn't change, but the resolution improves. 

Here, finally, are three overloads of LoadBitmapAsync, each of which returns a BitmopSource. 
Somewhat different approaches are used to obtain I Random A ccessS tream objects for the image and 
its thumbnail, and then a common routine loads the file with code you’ve already seen. 
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Project: PhotoScatter | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 


async Tasl«BitmapSource> LoadBitmapAsyncCStorageFi1 e storageFile) 

{ 

BitmapSource bitmapSource = null; 

// Open the StorageFi1e for reading 

using (IRandomAccessStreamWithContentType stream = await storageFile.OpenReadAsyncO) 

{ 

bitmapSource = await LoadBitmapAsync(stream); 

} 

return bitmapSource; 

} 

async Task<BitmapSource> LoadBi tmapAsync(StorageItemThumbnai 1 thumbnail) 

{ 

return await LoadBitmapAsync(thumbnai1 as IRandomAccessStream) ; 

} 

async Task<BitmapSource> LoadBitmapAsync (IRandomAccessStream stream) 

{ 

WriteableBitmap bitmap = null; 

// Create a BitmapDecoder from the stream 
BitmapDecoder decoder = null; 

try 

decoder = await BitmapDecoder .CreateAsyncCstream); 

} 

catch 

{ 

// Just skip ones that aren't valid 
return null; 

} 

// Get the first frame 

BitmapFrame bitmapFrame = await decoder.GetFrameAsync(O); 

// Get the pixels 
PixelDataProvider dataProvider = 

await bitmapFrame.GetPixelDataAsync (Bi tmapPixelFormat. Bgra8, 

BitmapAlphaMode. Premultipiied, 

new BitmapTransformO , 

ExifOrientationMode. RespectExifOrientation, 
ColorManagementMode .ColorManageToSRgb); 

byte[] pixels = dataProvider.DetachPixelData(); 

// Create WriteableBitmap and set the pixels 

bitmap = new WriteableBi tmap((i nt)bi tmapFrame.PixelWidth, 

(int) bitmapFrame.PixelHeight); 
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using (Stream pixel Stream = bitmap. Pixel Buffer .AsStreamO) 
{ 

pixelStream.Write(pixels, 0, pixels■Length); 

} 

bitmap.Invalidate(); 
return bitmap; 



Capturing Camera Photos 


You've seen how Windows Runtime applications can create WriteobleBitmop objects from scratch 
or load existing bitmaps from files. There are other ways that programs can obtain bitmaps. In 
Chapter 17, "Share and Print," for example, you’ll see how programs can obtain bitmaps from other 
applications, either directly or through the clipboard. 

Your application can also get a bitmap from the computer’s built-in camera. There are two 
approaches, and if you’re willing to yield control to Windows 8 so that the operating system can 
display its normal camera interface, this process is exceptionally easy. 

To enable your application to use the computer’s camera, you must indicate that in the Package 
•appxmanifest file. In Visual Studio, open that file, select the Capabilities tab, and click Webcam. 


I’ve done that for the EasyCameraCapture program. Here’s the MainPage.xaml file: 

Project: EasyCameraCapture | File: MainPage.xaml (excerpt) 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

<Image Name="image" /> 

<Button Content="Capture Photo!" 

FontSize="48" 

HorizontalA1i gnment="Left" 

VerticalAli gnment="Top" 

Cli ck="OnButtonCl ick" /> 

</Grid> 

The Click handler for the Button instantiates the Camera Capture Ul class defined in the 
Windows.MecJia.Copture namespace and calls CaptureFileAsync: 


Project: EasyCameraCapture | File: MainPage.xaml.es (excerpt) 

async void OnButtonCli ck(object sender, RoutedEventArgs args) 

{ 

CameraCaptureUI cameraCap = new CameraCaptureUIO ; 

StorageFi1e storageFi1e = await cameraCap.CaptureFi1 eAsyncCCameraCaptureUIMode .Photo); 


if (storageFi1e != null) 

{ 

IRandomAccessStreamWithContentType stream = await storageFile.OpenReadAsyncO; 
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Bitmaplmage bitmap = new Bitmaplmage() ; 

await bitmap.SetSourceAsync(stream); 
image.Source = bitmap; 



Prior to calling CoptureFileAsync a program can set various properties of CameraCaptureUI to 
select a file format, select a pixel size, enable cropping, and so forth. 

When your application calls CoptureFileAsync, Windows 8 switches to a screen that looks very 
much like the normal Windows 8 Camera application. The only substantial differences are that the 
Video Mode button is disabled (but that can be enabled by passing CameraCaptureUI Mode 
.PhotoOrVideo to the CaptureFileAsync method) and a circled left arrow appears in the upper-left 
corner. 

To return to the EasyCameraCapture application, you can press that circled left arrow, in which 
case the returned Storage File is null. Or you can capture a picture by tapping or clicking the screen 
and then pressing a circled check mark at the bottom. 

On return to the program, the StorogeFile object references a file stored in the TempStote directory 
of the application’s local storage. The code in EasyCameraCapture simply displays the file: 



Your application might want to invoke a FileSovePicker to let the user save the image, or you can 
save it automatically somewhere in the Pictures library. Perhaps your application does something 
unique with captured images and a special directory in the Pictures library would be convenient. (The 
standard Windows 8 Camera application stores photos in the Camera Roll directory of Pictures.) For 
doing this, you’ll need to set your application capabilities to allow access to the Pictures library, just as 
the regular Windows 8 Camera application does. 
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You can drop to a lower level of interface to the camera and basically write your own complete 
camera application, including a video preview, selection of camera (if more than one), triggering the 
photo capture, and so forth. 

The HarderCameraCapture project shows the basics. The XAML file contains something you 
haven’t seen before — a CaptureElement for previewing the video — as well as an old friend: 


Project: HarderCameraCapture I File: MainPage.xaml (excerpt) 

<Crid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<CaptureElement Name="captureEl ement" /> 

<Image Name="image" /> 

</Crid> 


The code-behind file uses the Loaded handler to perform initialization. The static 
Devicelnformation. Find AllAsync method allows obtaining a collection of video capture devices. The 
Devicelnformotion object contains a string ID and an EnclosureLocotion property that lets the program 
determine where on the computer each camera is located. This code attempts to find the camera on 
the front, but if it can’t, it settles for the first (or possibly only) camera in the collection: 

Project: HarderCameraCapture I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

MediaCapture mediaCapture = new MediaCapture() ; 


public MainPage() 

{ 

this .InitializeComponent(); 
Loaded += OnMainPageLoaded; 

} 


async void OnMai nPageLoaded(object sender, RoutedEventArgs args) 

{ 

DevicelnformationCol1ection devlnfos = 

await Devicelnformation .FindAl lAsync(Devi ceClass .VideoCapture); 

if (devlnfos.Count == 0) 

{ 

await new MessageDial og("No video capture devices found") .ShowAsyncO; 
return ; 

} 

string id = null; 

// Try to find the front webcam 

foreach (Devicelnformation devlnfo in devlnfos) 

{ 

if (devlnfo.EnelosureLocation != null && 

devlnfo.Enelosu reLocation.Panel == Windows■Devices■Enumeration. Panel. Front) 
id = devlnfo.Id; 

} 


774 PART: Specialties 



// If not available ， just pick the first one 
if (id == null) 

id = devlnfos[0]•Id; 

// Create initialization settings 

MediaCapturelnitializationSettings settings = new MediaCapturelnitializationSettings (); 

settings.VideoDeviceld = i d; 

setti ngs.Streami ngCaptureMode = St reamingCaptu reMode .Video; 

// Initialize the MediaCapture device 

await mediaCapture.InitializeAsync(settings); 


// Associate with the CaptureElement 
captureElement.Source = mediaCapture; 

// Start the preview 

await medi aCaptu re. StartPrevi ewAsyncQ ; 


Once a device ID has been obtained, the Loaded handler continues by creating a 
MediaCapturelnitiolizotionSettings object and uses this to initialize a MedioCopture object defined as 
a field. This MedioCopture object is made the source of the CoptureElement instantiated in the XAML 
file. 

At the conclusion of the Loaded handler, the preview is working. If a camera was found located on 
the front of the computer, you should be staring at a live video feed of yourself. 

I’ve also implemented a Tapped handler for snapping a photo. The MedioCopture class has both 
CopturePhotoToStorogeFileAsync and CopturePho toToStre am A syn c methods. I’ve chosen to use the 
stream approach and capture the photo to a memory stream. At that point a BitmopDecoder can 
obtain the pixel bits. The program borrows the HSL structure from the FingerPaint program to in¬ 
crease the saturation of all the pixels and then creates a WriteableBitmop from that: 

Project: HarderCameraCapture I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

bool ignoreTaps = false; 

async protected override void OnTapped(TappedRou tedEventArgs args) 

{ 

if (ignoreTaps) 
return ; 

// Capture photo to memory stream 

ImageEncodingProperties imageEncodingProps = ImageEncodingProperties .CreateJpegO; 
InMemoryRandomAccessStream memoryStream = new InMemoryRandomAccessStreamO ; 

await mediaCapture.CapturePhotoToStreamAsync(imageEncodingProps, memoryStream); 
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// Use BitmapDecoder to get pixels array 

BitmapDecoder decoder = await BitmapDecoder .CreateAsync(memoryStream); 
PixelDataProvider pixel Provider = await decoder.GetPixelDataAsyncC); 
byte[] pixels = pixel Provider.DetachPixelData(); 


// Saturate the colors 

for (i nt index = 0; index < pixels.Length; index += 4) 

{ 

Col or color = Color. FromArgb(pixels[index + 3], 

pixels[index + 2], 
pixels[index + 1], 
pixels[index + 0]); 

HSL hsl = new HSL(color); 

hsl = new HSL(hsl.Hue, 1.0, hsl.Lightness); 

color = hsl.Color; 



pixels [index + 
pixels [index + 
pixels [index + 
pixels [index + 


0] = color.B 

1] = color.G 

2] = color.R 

3] = color.A 


// Create a WriteableBitmap and initialize it 

WriteableBitmap bitmap = new WriteableBi tmap((i nt)decoder.PixelWidth, 

(i nt)decoder.PixelHeight); 
Stream pi xel Stream = bi tmap. Pi xel Buffer .AsStreamO ; 
await pixel Stream.WriteAsyncCpixels, 0, pixels.Length); 
bitmap.Invalidate(); 


// Display the bitmap 
image.Source = bitmap; 

// Set a timer for the image 
DispatcherTimer timer = new DispatcherTimer 
{ 

Interval = TimeSpan .FromSeconds(2.5) 

}； 

timer.Tick += OnTimerTick; 
timer.Start(); 
ignoreTaps = true ; 

base.OnTapped(args); 


void OnTimerTi ck(object sender, object args) 

{ 

// Disable the timer 

DispatcherTimer timer = sender as Di spatcherTimer; 

timer.Stop(); 

timer.Tick -= OnTimerTick; 
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// Get rid of the bitmap 
image.Source = null; 
ignoreTaps = false; 



I don’t want the picture to stick around forever, so the program sets a DispotcherTimer for 2.5 
seconds. During this time, further taps are ignored, but after that period the photo is simply removed 
from the screen and we Ye back to the live video feed. 

Of course, highly saturated colors can be somewhat frightening: 
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CHAPTER 15 

Going Native 


I n the world of Windows 8 programming, it is a sad truth that all languages are not created equal. 

In theory, any programming language can access any class or function available to Windows Store 
applications, but that’s only because the entire API is built on top of the Component Object Model 
(COM). In the real world of sane programming, the ease of accessing certain areas of the Windows 8 
API depends on what programming language you're using. 

For example, only programmers working with the managed languages of C# and Visual Basic have 
direct access to the .NET APIs for Windows 8 applications — those namespaces beginning with the 
word System. C++ programmers are expected to use C++ runtime libraries and classes in the Platform 
namespace for equivalent functionality. 

On the other hand, Windows 8 applications can access a subset of the Win32 and COM API, but 
these functions and classes are only conveniently available to C++ programmers. To get at these same 
APIs, C# programmers need to jump through hoops. 

This is a chapter showing how to jump through those hoops. I’ll discuss two basic techniques. The 
first is called Platform Invoke (also known as Plnvoke or P/Invoke), which has existed from the very 
beginning of .NET programming for accessing Win32 functions or functions in other dynamic-link 
libraries (DLLs). P/Invoke is particularly suited for accessing a "flat” API — that is, one in which functions 
are independent (or perhaps reference handles provided by other functions) rather than being 
consolidated into classes. 

The second technique involves writing a "wrapper" DLL in C++ and then accessing that DLL from a 
C# program. This technique is more suited for object-oriented APIs and, in particular, the big chunk of 
high-performance graphics and audio classes collectively known as DirectX. 

In a Windows 8 application, a DLL written in one language and accessed by another must be in a 
special format known as a Windows Runtime Component. Visual Studio lets you create a Windows 
Runtime Component, but there are a bunch of rules and restrictions on what these libraries may do. 

Keep in mind that you can’t use either of these techniques to give your program access to 
functions that aren’t allowed in Windows Store applications. You can't use these techniques to access 
arbitrary Win32 functions. You're restricted to those in the subset allowed for Windows 8 applications. 
Nor can you call functions in DLLs that make calls to Win32 functions not in this subset. 
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An Introduction to P/Invoke 


Suppose you're browsing through the subset of Win32 functions allowed for new Windows 
8 applications and you encounter one that you’d like to use. Here’s the way it appears in the 
documentation: 

void WINAPI GetNativeSystemInfo( — out LPSYSTEM_INFO 1pSystemlnfo); 

If you’re completely unfamiliar with the Win32 API, this is likely to look like gibberish. 

The uppercase identifiers are generally defined using C ^define or fypec/ef statements in the 
various Windows header files. You’ll find these header files in subdirectories of the 
C./Progrom Files (x86)/Windows Kits/8.0 directory on the machine on which youVe installed 
Visual Studio. The most basic are Windows.h, WinDef.h, WinBase.h, and winnt.h. The WINAPI 
identifier is the same as ― stdcall, which is the standard calling convention for C programs calling 
Win32 functions. LPSYSTEMJNFO is a long pointer — "long” meaning wider than a 16-bit pointer such 
as existed back when Windows was a wee child — to a SYSTEMJNFO structure. The SYSTEMJNFO 
structure is defined like this: 


typedef struct _SYSTEM_INFO { 
uni on { 

DWORD dwOemld; 
struct { 

WORD wProcessorArchi tecture; 
WORD wReserved; 


}； 

}； 

DWORD 

LPVOID 

LPVOID 


dwPageSi ze; 

1pMinimumApplicationAddress; 
1pMaximumApplicationAddress; 


DWORD PTR dwActiveProcessorMask 


DWORD 

DWORD 

DWORD 

WORD 

WORD 


dwNumberOfProcessors; 
dwProcessorType; 
dwAl1ocationGranulari ty; 
wProcessorLevel; 
wProcessorRevisi on; 


} SYSTEM_INFO; 


The prefacing of field names with lowercase abbreviations of the data types is a form of simple 
Hungarian notation, so called because it was invented by Hungarian-born Charles Simonyi. Hungarian 
notation was popularized by the Windows API and some ancient books on Windows programming, 
but it is no longer widely used in application programming. 


In Windows parlance, a WORD is a 16-bit unsigned value, which C# programmers know as a 
ushort. The DWORD is a double-WORD, or a 32-bit unsigned value or a uint. Watch out for references 
to long, which is not a 64-bit C# long but instead a C++ long, which is the same size as an int, or 
32 bits. 
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LPVOID translates as a "long pointer to void" or, in standard C, void *, and DWORD_PTR is either 
an unsigned 32-bit or 64-bit integer, depending on whether Windows is running on a 32-bit or 64-bit 
processor. These are equivalent to the C# IntPtr. 


The reason you need to know how these Windows API data types correspond to C# data types 
is because to use this structure from a C# program you need to redefine it in C#. Fortunately, the 
documentation of SYSTEM JNFO indicates that the dwOemld field is obsolete, which means that you 
can ignore the union and simply create a straight C# structure with public fields, perhaps giving the 
structure a more C#-ish name in the process: 


struct Systemlnfo 
{ 

public ushort wProcessorArchitecture; 
public ushort wReserved; 
public uint dwPageSize; 

public IntPtr 1 pMinimumApplicationAddress; 
public IntPtr 1 pMaximumApplicationAddress; 
public IntPtr dwActiveProcessorMask; 
public uint dwNumberOfProcessors; 
public uint dwProcessorType; 
public uint dwAl1ocationGranularity; 
public ushort wProcessorLevel; 
public ushort wProcessorRevision; 


In C# the fields must be defined as public if you want to access them from outside the structure. If 
you want, you can also rename all the fields (for example, ProcessorArchitecture and PageSize). 

You can also specify different data types of the same size — for example, short rather than ushort 
and int rather than uint — if you know that the actual values won’t overrun the signed types. To the 
Windows API, all you’re doing is supplying a block of memory. The total structure occupies 36 bytes 
of memory in 32-bit Windows and 48 bytes in 64-bit Windows. 

Very often in P/Invoke code you’ll see such a structure preceded by the following attribute: 

[StructLayout(LayoutKind .Sequent!al)] 
struct Systemlnfo 


The StructLoyoutA ttribute class and the Layout Kind enumeration are defined in the System 
.Runtime.InteropServices namespace, which has lots of other classes related to P/Invoke. This attribute 
indicates explicitly that these fields should be treated as contiguous and aligned on byte boundaries. 

Now that you have a structure to be passed to the G etNativeSystemlnfo function, you must declare 
the function itself. In doing so, you make use of the DIIImportAttribute, also defined in System 
.Runtime.InteropServices. At the very least you must indicate the dynamic-link library in which this 
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function can be found. The documentation indicates that GetNotiveSystemlnfo is defined in 
kernel32.dll. Here’s the function declaration: 

[D1 1 Import ("kernel 32.dll") ] 

static extern void GetNativeSystemInfo(out Systemlnfo systemlnfo); 

This declaration must appear inside a C# class definition at the same level as the other methods. 
The function must be declared as static, which is common in regular C# classes, but also as extern, 
which is not common but means that the actual implementation of this function is external to the 
class. If you want the function to be visible outside the class, give it a public keyword as well. 

With the exception of extern, the function declaration otherwise appears to be a C# method. The 
method returns void, and the single argument is a reference to a Systemlnfo object. Many Windows 
API calls require or return information in structures passed as arguments using pointers, and you’ll 
define those arguments by using either out or ref. These are functionally identical, but with ref the C# 
compiler checks to see that you’ve initialized the value type before calling the function. 

In some other method of the class, you can define a value of type Systemlnfo and call the function 
as if it’s a normal static method: 


Systemlnfo systemlnfo; 

GetNati veSystemInfo(out systemlnfo); 

Let’s see how this works in the context of a complete program. The XAML file for 
SystemlnfoPInvoke uses a Grid to format the information available from GetNotiveSystemlnfo in a 
table: 

Project: SystemlnfoPInvoke | File: MainPage.xaml (excerpt) 

<Page 

FontSi ze="24"> 


<Page.Resources 〉 

<Style x : Key=" rightJustifiedText" TargetType="TextBlock"> 
〈Setter Property="TextAl ignment" Val ue="Ri ght" /> 
〈Setter Property="Margi n" Value="12 0 0 0" /> 
</Style> 

</Page.Resources 〉 


<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Grid HorizontalAli gnment="Center" 

VerticalA1i gnment="Center"> 

<Grid.RowDefinitions> 


<RowDefinition 
<RowDefinition 
<RowDefinition 
<RowDefinition 
<RowDefinition 
<RowDefinition 
<RowDefinition 
<RowDefinition 
<RowDefinition 


Hei ght="Auto" 
Height="Auto" 
Hei ght="Auto" 
Height="Auto" 
Hei ght="Auto" 
Hei ght="Auto" 
Hei ght="Auto" 
Hei ght="Auto" 
Height="Auto" 


/> 

/> 

/> 

/> 

/> 

/> 

/> 

/> 

/> 


</Grid.RowDefinitions> 
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<Grid.ColumnDefinitions> 

<ColumnDefinition Wi dth="Auto" /> 
<ColumnDefinition Width="Auto" /> 
</Grid.ColumnDefiniti ons> 


〈TextBlock Text="Processor Architecture: " Grid. Row="0" Grid.Col umn="0" /> 
〈TextBlock Name="processorArchi tecture" Grid. Row="0" Grid.Column="l" 

Styl e="{StaticResource rightJustifi edText}" /> 


〈TextBlock Text="Page Size: " Grid. Row="l" Grid.Col umn="0" /> 
〈TextBlock Name="pageSi ze" Grid.Row="l" Grid.Col umn="l" 

Style="{StaticResource rightJustifi edText}" /> 


〈TextBlock Text="Mi nimum Application Addresss: " Grid. Row="2" Grid.Column="0" /> 
〈TextBlock Name="mi nAppAddr" Grid. Row="2" Grid.Column="l" 

Styl e="{StaticResource rightJustifiedText}" /> 


<TextBlock Text="Maximum Application Addresss: " Grid. Row="3" Grid.Column="0" /> 
〈TextBlock Name="maxAppAddr" Grid. Row="B" Grid.Column="l" 

Styl e="{StaticResource rightJustifi edText}" /> 


〈TextBlock Text="Acti ve Processor Mask: " Grid. Row="4" Grid.Col umn="0" /> 
<TextBlock Name="acti veProcessorMask" Grid. Row="4" Grid.Column="l" 
Style="{StaticResource rightJustifiedText}" /> 


〈TextBlock Text="Number of Processors: " Grid. Row="5" Grid.Col umn="0" /> 
<TextBlock Name=" numberProcessors" Grid. Row="5" Grid.Col umn="l" 

Styl e="{StaticResource rightJustifiedText}" /> 


〈TextBlock Text="Al location Granularity: " Grid. Row="6" Grid.Col umn="0" /> 
〈TextBlock Name="al locationGranularity" Grid. Row="6" Grid.Column="l" 

Styl e="{StaticResource rightJustifiedText}" /> 


〈TextBlock Text="Processor Level: " Grid.Row="7" Grid.Col umn="0" /> 
<TextBlock Name="processorLevel " Grid. Row="7" Grid.Column="l" 
Style="{StaticResource rightJustifiedText}" /> 


〈TextBlock Text="Processor Revision: " Grid. Row="8" Grid.Column="0" /> 
<TextBlock Name="processorRevi sion" Grid.Row="8" Grid.Column="l" 

Styl e="{StaticResource rightJustifiedText}" /> 

</Grid> 

</Gri d> 

</Page> 


In the code-behind file, both the structure and the external function declaration are defined within 
the Main Page class. The external function must be declared within a class definition, but the structure 
need not be, and it can be in a different file entirely, just like any normal C# structure. Here’s the 
complete code-behind file: 


Project: SystemlnfoPInvoke | File: MainPage.xaml.es 
using System; 

using System.Runtime.InteropServices; 
using Windows.UI.Xaml.Controls; 
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namespace SystemlnfoPInvoke 


public sealed partial cl ass MainPage : Page 

{ 

[St ructLayout (LayoutKi nd ■Sequent!al)] 
struct Systemlnfo 
{ 

public ushort wProcessorArchitecture; 
public byte wReserved; 
public uint dwPageSize; 

public IntPtr 1pMinimumApplicationAddress; 
public IntPtr 1pMaximumApplicationAdd ress; 
public IntPtr dwActiveProcessorMask; 
public uint dwNumberOfProcessors; 
public uint dwProcessorType; 
public uint dwAl1ocationGranularity; 
public ushort wProcessorLevel; 
public ushort wProcessorRevisi on; 

} 

[Dll Import ("kernel32.dll ")] 

static extern void GetNati veSystemInfo(out Systemlnfo systemlnfo); 

enum ProcessorType 

{ 

x86 = 0 ， 

ARM = 5, 
ia64 = 6, 
x64 = 9, 

Unknown = 65535 

}； 

public MainPageO 

{ 

this .InitializeComponentC); 

Systemlnfo systemlnfo = new SystemlnfoO; 

GetNativeSystemInfo(out systemlnfo); 

processorArchitecture.Text = 

C (ProcessorType) systemlnfo.wProcessorArchitecture).ToString(); 
pageSize.Text = systemlnfo.dwPageSize.ToString(); 

minAppAddr.Text = C(ulong) systemlnfo.1pMinimumApplicationAddress).ToStri ng("X") ; 

maxAppAddr.Text = C(ulong) systemlnfo.1pMaximumApplicationAddress).ToStri ng("X") ; 

activeProcessorMask.Text = ((ulong)systemlnfo. dwActiveProcessorMask).ToStri ng("X") ; 

numberProcessors.Text = systemlnfo.dwNumberOfProcessors.ToStri ng("X") ; 

al1ocationGranularity.Text = systemlnfo.dwAl1ocationGranularity.ToString(); 

processorLevel.Text = systemlnfo.wProcessorLevel.ToString(); 

processorRevisi on.Text = systemlnfo.wProcessorRevisi on.ToStri ng("X") ; 



The documentation indicates that the wProcessorArchitecture field can take on values of 0 (for 
x86 architectures), 6 (for Intel Itanium), 9 (for x64), and OxFFFF for "unknown.’’ The value for ARM 
processors (such as the first release of the Microsoft Surface) isn’t indicated in the documentation I’m 
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seeing, but all the possible values are constants beginning with PROCESSOR_ARCHITECTURE defined 
in winnt.h, and PROCESSOR_ARCHITECTURE_ARM is defined as 5. 

To ease the formatting of the wProcessorArchitecture value, I defined a little enum called 
ProcessorType and cast the wProcessorArchitecture value to that enumeration. For the IntPtr fields, I 
cast to ulong and then displayed them as hexadecimal. Here’s the screen running on the tablet I’m 
using to write this book: 


Processor Architecture: 

x64 

Page Size: 

4096 

Minimum Application Addresss: 

10000 

Maximum Application Addresss: 

FFFFFFFFFFFEFFFF 

Active Processor Mask: 

F 

Number of Processors: 

4 

Allocation Granularity: 

65536 

Processor Level: 

6 

Processor Revision: 

2A07 


That tablet has a 64-bit processor. Running on the Microsoft Surface, the program looks like this: 


Processor Architecture: 

ARM 

Page Size: 

4096 

Minimum Application Addresss: 

10000 

Maximum Application Addresss: 

7FFEFFFF 

Active Processor Mask: 

F 

Number of Processors: 

4 

Allocation Granularity: 

65536 

Processor Level: 

3081 

Processor Revision: 

209 
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Some Help 


When you use P/Invoke to define structures and declare functions, you are taking on the 
responsibility for getting it right. You must supply the correct filename of the DLL in which the 
function is located, for example. (While I began developing the first project in this chapter I typed 
〃 kernel32 」 ib 〃 rather than "kernel32.dll” and couldn’t figure out why it wasn’t working.) If you’re 
accessing something other than a system DLL, you must make sure the DLL is referenced by the 
application. You must also spell the function name correctly and declare all the arguments correctly. 
There’s no IntelliSense for P/Invoke! 


These structures and function declarations can often be complex. To help out, there is a wiki 
website www.pinvoke.net, to which many people have contributed structure definitions and function 
declarations that you can just copy and paste into your own code. You’re even allowed to contribute 
some of your own! 


Time Zone Information 


Suppose you’d like to write a Windows Store application that displays a bunch of clocks set for various 
locations around the world, perhaps similar to the ClockRack program I wrote for PC Magazine back 
in the year 2000. Perhaps the Windows 8 version would look something like this: 


New York City London 



Thursday, November 8, 2012 1:04 PM Thursday, November 8, 2012 12:04 PM 


Thursday, November 8, 2012 10:04 AM 



San Francisco 



Such a program would let you add new clocks, set their locations and time zones, give them unique 
colors, and retain this information in application settings. 

It would be great to take advantage of the built-in support of Windows for computing the time in 
various time zones and particularly for handling the problem of daylight saving time (known in some 
places as "summer time"). 
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You might be very enthusiastic upon finding the TimeZonelnfo class in the System namespace and 
noting that the static G etSystemTimeZones method returns a collection of TimeZonelnfo objects for all 
the time zones around the world. However, when you try to use this method, you’ll discover that it’s 
not available for Windows 8 applications. The only TimeZonelnfo object you can obtain in a Windows 
8 application is one that’s appropriate for the current system time zone setting or the trivial one for 
Universal Coordinated Time (UTC), also known (more commonly but less accurately) as Greenwich 
Mean Time. 

However, a Windows 8 application does have access to several Win32 functions that provide much 
of the information you’ll need. The Win32 EnumDynamicTimeZonelnformation function enumerates 
all the time zones around the world in the form of DYNAMIC_TIME_ZONE_INFORMATION structures: 


typedef struct _TIME_DYNAMIC_ZONE_INFORMATION { 
LONG Bias; 

WCHAR StandardName[32]; 

SYSTEMTIME StandardDate; 


LONG StandardBias; 

WCHAR DaylightName[32]; 

SYSTEMTIME DaylightDate; 

LONG DaylightBias; 

WCHAR TimeZoneKeyName[128]; 

BOOLEAN DynamicDaylightTimeDisabled; 

DYNAMIC_TIME_ZONE_INFORMATION, *PDYNA 町 C—TIME_ZONE_INFORMATION; 


This is an extended version of the TIME_ZONE_INFORMATION structure: 


typedef struct —TIME—ZONE_INFORMATION { 
LONG Bias; 

WCHAR StandardName[32]; 

SYSTEMTIME StandardDate; 

LONG StandardBias; 


WCHAR DaylightName[32]; 

SYSTEMTIME DaylightDate; 

LONG DaylightBias; 

} TIME_ZONE_INFORMATION, *PTIME_ZONE_INFORMATION; 


WCHAR is a wide 16-bit Unicode character, and arrays of these characters are essentially 
zero-terminated strings. The StondordName is a string like "Eastern Standard Time”, and 
DoylightName is a string like "Eastern Daylight Time". The TimeZoneKeyName in the DYNAMIC_TIME_ 
ZONE_INFORMATION structure is a key used in the Windows registry. In Windows 8, these registry 
entries can be found at HKEY_LOCAL_MACH IN E/SOFTWARE/M icrosoft/Windows NT/CurrentVersion/ 
Time Zones, and the registry key matches StandardName. 


The Bias field is a number of minutes to subtract from Universal Coordinated Time to get local 
time. For the eastern US time zone, that’s 300 minutes. The StandordBias is always zero, while 
DaylightBias is the number of minutes to subtract from standard time to convert to summer time, 
usually -60. 
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The DoylightDote and StondardDate fields indicate when the switch to daylight saving time and 
back to standard occurs, and they are of type SYSTEMTIME: 

typedef struct _SYSTEMTIME { 

WORD wYear; 

WORD wMonth; 

WORD wDayOfWeek; 

WORD wDay; 

WORD wHour; 

WORD wMinute; 

WORD wSecond; 

WORD wMilliseconds; 

} SYSTEMTIME, *PSYSTEMTIME; 

The SYSTEMTIME structure is mostly used with the Win32 GetLocolTime and GetSystemTime 
functions to obtain current local time and UTC, respectively. The SYSTEMTIME values in the 
TIME_ZONE_INFORMATION structure are specially coded for the purpose of indicating a transition 
date: The wHour and wMinute fields indicate the time of the transition, the wMonth field indicates 
the month of the transition (for example, 3 for March), the wD ay Of Week field indicates the day of the 
week of the transition (for example, 1 for Sunday), and the wDoy field indicates the particular occur¬ 
rence of that day of the week within the specified month (for example, 2 for the second Sunday of the 
month or 5 for the last Sunday). 

Windows makes a distinction between locales that switch between standard time and daylight 
saving time on days indicated like that and those locales that dynamically change the date every year. 
These latter are referred to as using Dynamic DST, but the information by year is not directly available. 

A function named GetTimeZonelnformotionForYeor accepts a year argument and a pointer 
to a DYNAMIC_TIME_ZONE_INFORMATION structure and returns a pointer to a 
TIME_ZONE_INFORMATION structure with the information appropriate for that year. The 
SystemTimeToTzSpecificLocolTime accepts a pointer to this TIME_ZONE_INFORMATION structure 
and a pointer to a SYSTEMTIME structure probably obtained from the GetSystemTime function and 
returns a SYSTEMTIME structure indicating local time for that time zone. Thus, it is not necessary for 
programs to perform their own time conversions. 

A program such as ClockRack needs a facility for the user to choose a time zone for a particular 
locale. Most preferable would be something consistent with the facility that Windows 8 provides for 
users to select a time zone. 

Take a look at what Windows 8 provides for users: Invoke the Windows 8 charms, select Settings, 
and tap the Change PC Settings label at the bottom. This invokes a program with the title PC Settings 
and a list. Select General, and you’ll see a combo box at the top with the time zones. Each time zone is 
identified by an offset from UTC, sometimes the name of the time zone, and often some sample cities. 
For example, for Romance Standard Time, the combo box displays 

(UTC+01:00) Brussels, Copenhagen, Madrid, Paris 

In the Windows registry section for time zones, you'll find these labels identified with a name of 
"Display,” but this information is not provided by the Win32 functions. You’d need to access the 
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registry to obtain it, and there are no Win32 functions available to Windows 8 applications to access 
the registry. 

Of course, nothing prevents you from writing a little desktop .NET program to access the full 
TimeZonelnfo class and format the resultant strings so that they define a Dictionary object that you 
can then include in a Windows 8 program. That’s what I’ve done here. The code in the .NET program I 
used to generate this list is shown in the comment above the Dictionary definition: 


Project: ClockRack I File: TimeZoneManager.Display.es (excerpt) 

namespace ClockRack 

{ 

public partial class TimeZoneManager 

{ 

// Generated from tiny .NET program: 

// foreach (TimeZonelnfo info in TimeZonelnfo.GetSystemTimeZones()) 

// Console.WriteLine("{{ \"{0}\", , info.StandardName, info.DisplayName); 

static Dicti onary<stri ng , string> displayStrings = new Dicti onary<st ring , string> 

{ 

{ "Dateline Standard Time" , "(UTC-12:00) International Date Line West" }, 

{ "UTC-11" , "(UTC-11:00) Coordinated Universal Time-11" }, 

{ "Hawaiian Standard Time" , "(UTC-10:00) Hawaii" }， 

{ "Alaskan Standard Time" , "(UTC-09:00) Alaska" }, 

{ "Pacific Standard Time (Mexico)", "(UTC-08:00) Baja California" }, 


{ "Kamchatka Standard Time" , "(UTC+12:00) Petropavlovsk-Kamchatsky - Old" }, 
{ "Tonga Standard Time" , "(UTC+13:00) Nuku'alofa" }, 

{ "Samoa Standard Time" , "(UTC+13:00) Samoa" } 

}； 

} 

} 


This dictionary is part of a class in the ClockRack project I called TimeZoneMonager. This is the class 
I’ve used to consolidate all the P/Invoke logic. No code outside of the TimeZoneMonager accesses any 
Win32 function or structure. 


The TimeZoneMonager class is designed to be instantiated only once and to be used for the 
duration of the application. The class makes time zone data available to the rest of the program as a 
collection of the following values: 


Project: ClockRack I File: TimeZoneDisplaylnfo.es 

namespace ClockRack 

{ 

public struct TimeZoneDisplaylnfo 

{ 

public int Bias { set; get; } 

public string TimeZoneKey { set ; get ; } 

public string Display { set; get ; } 
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The Bias property is only used for sorting. The TimeZoneKey is the same string as the 
TimeZoneKeyNome in the DYNAMIC_TIME_ZONE_INFORMATION structure, and the Display property 
is obtained from the disployStrings dictionary. 

The portion of the TimeZoneManoger class in the main TimeZoneManager.es file begins by 
defining the necessary Win32 structures and declaring three Win32 functions the class requires: 


Project: ClockRack I File: TimeZoneManager.es (excerpt) 


public partial class TimeZoneManager 


[StructLayout(LayoutKind •Sequential)] 
struct SYSTEMTIME 



public 
public 
public 
public 
public 
public 
public 
public 


ushort wYear; 
ushort wMonth; 
ushort wDayOfWeek; 
ushort wDay; 
ushort wHour; 
ushort wMinute; 
ushort wSecond; 
ushort wMilliseconds; 


[StructLayout(LayoutKind .Sequential, CharSet = CharSet .Uni code)] 
struct TIME_ZONE_INFORMATION 
{ 

public int Bias; 

[Marshal As(UnmanagedType. ByValTStr, SizeConst = 32)] 
public string StandardName; 
public SYSTEMTIME StandardDate; 
public int StandardBias; 

[Marshal As(UnmanagedType .ByValTStr, SizeConst = 32)] 
public string DaylightName; 
public SYSTEMTIME DaylightDate; 
public int DaylightBias; 

} 


[StructLayout(LayoutKind .Sequential, CharSet = CharSet .Uni code)] 
struct DYNAMIC_TIME_ZONE_INFORMATION 
{ 

public int Bias; 

[Marshal As(UnmanagedType .ByValTStr, SizeConst = 32)] 
public string StandardName; 
public SYSTEMTIME StandardDate; 
public int StandardBias; 

[Marshal As(UnmanagedType. ByValTStr, SizeConst = 32)] 
public string DaylightName; 
public SYSTEMTIME DaylightDate; 
public int DaylightBias; 

[Marshal As(UnmanagedType .ByValTStr, SizeConst = 128)] 

public string TimeZoneKeyName; 

public byte DynamicDaylightTimeDisabled; 

} 

[Dll Import ("Advapi32.dll")] 
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static extern uint EnumDynamicTimeZoneInformation(ui nt index ， 

ref DYNAMIC_TIME_ZONE_INFORMATION dynamicTzi); 

[Dll Import ("kernel32.dll")] 

static extern byte GetTimeZonelnformati onForYear(ushort year, 

ref DYNAMIC—TIME_Z0NE—INFORMATION dtzi , 
out TIME_ZONE_INFORMATION tzi); 


[Dll Import ("kernel32.dll")] 

static extern byte SystemTimeToTzSpecificLocalTi me(ref TIME_ZONE_INFORMATION tzi, 

ref SYSTEMTIME utc, out SYSTEMTIME local); 


Youll recall that several of the fields in the DYNAMIC_TIME_ZONE_INFORMATION and TIME— 
ZONEJNFORMATION structures are defined as arrays of WCHAR. This wouldn't work in C# because 
a C# array is always a pointer to memory allocated from the heap. Instead, the MorsholAs attribute 
allows indicating that these fields should be treated as C# strings of a particular maximum length. 

The constructor of the TimeZoneManoger class repeatedly calls EnumDynamicTimeZonelnformation 
until it returns a nonzero value, indicating that it’s at the end of the list. The number of items might 
change slightly with different versions of Windows, but I'm seeing a total of 101. Each item is stored in 
a private dictionary, and each item is also turned into a TimeZoneDisplaylnfo value and added to the 
publicly available collection named Displaylnformation : 

Project: ClockRack I File: TimeZoneManager.es (excerpt) 

public partial class TimeZoneManager 

{ 

// Internal dictionary for looking up DYNAMIC—TIME_ZONE_INFORMATION values from keys 
Dicti onary<stri ng , DYNAMIC_TIME_ZONE_INFORMATION 〉 dynamicTzis = 

new Dicti onary<st ring, DYNAMIC_TIME_ZONE_INFORMATION>() ; 

public TimeZoneManagerO 

{ 

uint index = 0; 

DYNAMIC_TIME_ZONE_INFORMATION tzi = new DYNAMIC_TIME_ZONE_INFORMATION() ; 

Li st<Ti meZoneDisplayInfo> displaylnformation = new List<TimeZoneDispl ayInfo>() ; 

// Enumerate through time zones 

while (0 == EnumDynamicTimeZonelnformation(index, ref tzi)) 

{ 

dynamicTzis.Add(tzi.TimeZoneKeyName, tzi); 

// Create TimeZoneDisplaylnfo for public property 

TimeZoneDisplaylnfo di spl aylnfo = new TimeZoneDisplaylnfo 

{ 

Bias = tzi■Bias ， 

TimeZoneKey = tzi.TimeZoneKeyName 

}； 

// Look up the display string 

if (displayStrings.ContainsKey(tzi.TimeZoneKeyName)) 
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chsplaylnfo.Display = displayStrings[tzi.TimeZoneKeyName]; 


else if (displayStrings.ContainsKeyCtzi.StandardName)) 

{ 

displaylnfo.Display = displayStrings[tzi.StandardName]; 

} 

//Or calculate one 
else 
{ 

if (tzi■Bias == 0) 

displaylnfo.Display = "(UTC) 

else 

displaylnfo.Display = String. Format ( M (UTC{0}{1:D2}:{2:D2})" , 

tzi.Bias > 0 ? : '+' , 

Math .Abs(tzi.Bias) / 60, 

Math .Abs(tzi•Bias) % 60); 
displaylnfo.Display += tzi.TimeZoneKeyName; 

} 

// Add to collection 
displaylnformation.Add(displaylnfo); 

// Prepare for next iteration 
index += 1; 

tzi = new DYNAMIC—TIME_Z0NE_INFORMATION (); 

} 

// Sort the display information iterns 

displaylnformation.Sort ((TimeZoneDisplaylnfo infol, TimeZoneDisplaylnfo info2)=> 

{ 

return info2.Bias.CompareTo(infol.Bias); 

})； 

// Set to the publicly available property 
this.Di splaylnformation = displaylnformation; 

} 

// Public interface 

public IList<TimeZoneDisplaylnfo Displaylnformation { protected set ; get; } 

} 

As you'll see shortly, this Display Info rm a ti on property is used as an ItemsSource for a ComboBox. 

The only remaining method in TimeZoneManager converts a UTC time into local time based on a 
time zone key value. This is the same string as the TimeZoneKeyName field of the DYNAMIC_TIME_ 
ZONEJNFORMATION structure and the TimeZoneKey property of the TimeZoneDisplaylnfo structure: 

Project: ClockRack I File: TimeZoneManager.es (excerpt) 

public partial class TimeZoneManager 

{ 

public DateTime GetLocalTime(stri ng timeZoneKey, DateTime utc) 

{ 

// Convert to Win32 SYSTEMTIME 
SYSTEMTIME utcSysTime = new SYSTEMTIME 
{ 
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wYear = (ushort)utc.Year, 

wMonth = (ushort)utc .Month, 

wDay = (ushort)utc.Day , 

wHour = (ushort)utc.Hour, 

wMinute = (ushort)utc.Mi nute, 

wSecond = (ushort) utc.Second, 

wMilliseconds = (ushort)utc .Millisecond 

}； 

// Convert to local time 

DYNAMIC_TIME_ZONE_INFORMATION dtzi = dynamicTzis[timeZoneKey]; 

TIME_ZONE_INFORMATION tzi = new TIME_ZONE_INFORMATION (); 

GetTimeZonelnformationForYearC (ushort) utc.Year, ref dtzi, out tzi); 

SYSTEMTIME localSysTime = new SYSTEMTIME (); 

SystemTimeToTzSpecificLoca!Time(ref tzi, ref utcSysTime, out localSysTime); 


// Convert SYSTEMTIME to DateTime 

return new DateTime (localSysTime.wYear, localSysTime.wMonth, 1ocalSysTime.wDay, 

1ocalSysTime.wHour, 1ocalSysTime.wMinute, 

1ocalSysTime.wSecond, 1ocalSysTime.wMilliseconds); 

} 


The method converts a .NET DateTime to a Win32 SYSTEMTIME, obtains a DYNAMIC_TIME_ZONE_ 
INFORMATION from the private dictionary, and then calls GetTimeZonelnformationForYear, which 
returns information in the form of a TIME_ZONE_INFORMATION structure, which is then passed to 
the SystemTimeToTzSpecificLocolTime function. The resultant SYSTEMTIME is converted back to a .NET 
DateTime. 

I’m not entirely happy with this method, and let me tell you why. The ClockRack program 
displays multiple clocks and uses a CompositionTorget.Rendering method to obtain an updated 
DateTime.UtcNow value, which it uses for all the clocks. (I figured this was probably more 
efficient than for this GetLocalTime method to call the Win32 GetSystemTime function to obtain 
a SYSTEMTIME value for UTC for each clock.) What I’m not happy about is repeatedly calling the 
GetTimeZonelnformationForYear method. This function really only needs to be called once for each 
time zone, and then the TIME_ZONE_INFORMATION can be reused in subsequent calls. However, if 
the program is running from December 31 to January 1, it needs to be called again for the New Year. I 
decided not to clutter up the class with logic of this sort. 

The year passed to GetTimeZonelnformationForYear should be a local year, not a UTC year, and 
that’s something else I’m not quite doing correctly. These two years are potentially only different 
during a 24-hour period surrounding the UTC New Year, and it really shouldn't matter in a program 
like this because the transition between standard time and daylight saving time occurs much later in 
the year. 

However, if a particular locale in the southern hemisphere decided to observe daylight saving time 
in one calendar year but not the next, or vice versa, that locale would experience a local time change 
at midnight on December 31 st , and the time would not be calculated incorrectly in the hours around 
New Year in the transition between those two years. 


But let’s move on. 
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You’ll recognize much of the actual clock (a User Control derivative called TimeZoneClock) from 
the AnalogClock program from Chapter 10, "Transforms," but I've converted it to use a view model 
through data bindings. I’ve also reduced all the coordinates and sizes by a factor of 10. Because there 
might be many clocks displayed in a very tiny space (such as a snapped view), the clocks must be 
able to vary widely in size. The approach I’ve used here — involving a Viewbox and a custom panel — 
worked best when the clocks had a defined size that was smaller than they would ever be. 

Another difference is that the analog clock face is now surrounded by two TextBlock elements. The 
top one displays a location, and the bottom one displays the current date and time. Without that text 
time at the bottom, you might be a little confused about whether the time was before noon or after. 

Each of the two TextBlock elements has a fixed height from the RowDefinition settings on the Grid, 
but they are also each in a Viewbox — if the text gets too long, it is compressed to fit. Overall, the 
entire clock is in a single-cell Grid with a Background property set to a binding. This Grid will occupy 
the full area available for it. Within that Grid is a Viewbox, which will adjust the size of its contents. 
Those contents are another Grid with a fixed size of 30 by 20, but the actual size is governed by the 
Viewbox based on available space: 

Project: ClockRack | File: TimeZoneClock.xaml (excerpt) 

<UserControl … 

Name="ctrl "> 


<UserControl.Resources 〉 

〈Style TargetType="TextBlock"> 

〈Setter Property="Margi n" Value="12 0" /> 

〈Setter Property="TextAl ignment" Val ue="Center" /> 
</Style> 


〈Style TargetType="Path"> 

〈Setter Property="StrokeThi ckness" Value="0.2" /> 
〈Setter Property="StrokeStartLi neCap" Val ue="Round" /> 
〈Setter Property="StrokeEndLi neCap" Val ue="Round" /> 
〈Setter Property="StrokeLi neJoin" Val ue="Round" /> 
〈Setter Property="StrokeDashCap" Val ue="Round" /> 
〈Setter Property="Fi 11" Value="Gray" /> 

</Style> 

</UserControl.Resources 〉 


<UserControl.Foreground 〉 

<SolidColorBrush Color="{Binding Foreground}" /> 
</UserControl.Foreground 〉 

<Gri d> 

<Grid.Background 〉 

<SolidColorBrush Color="{Binding Background}" /> 
</Grid.Background 〉 

<Viewbox> 

〈Grid Width=__20" 

Height="30" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Center"> 
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<Grid.RowDefinitions> 

<RowDefinition Height="5" /> 
<RowDefinition Height="20" /> 
〈RowDefinition Height="5" /> 
</Crid.RowDef i niti ons> 


<Viewbox Grid. Row="0"> 

〈TextBlock Text="{Bi nding Location}" /> 
</Viewbox> 


〈Grid Grid. Row="l"> 

<!-- Transform for entire clock --> 

<Grid.RenderTransform> 

<TranslateTransform X="10" Y="10" /> 
</Grid.RenderTransform> 


<!-- Small tick marks --> 

<Path Fill="{x:Null}" 

Stroke="{Binding ElementName=ctrl , Path=Fo reground}" 
StrokeThi ckness="0 .3" 

StrokeDashArray="0 3.14159"> 

<Path.Data> 

<E11ipseGeometry Radi usX="90" Radi usY="90" /> 
</Path.Data> 

</Path> 


<!-- Large tick marks --> 

<Path FilU'^xiNull}" 

Stroke="{Binding El ementName=ctrl , Path=Fo reground}" 
StrokeThi ckness="0 .6" 

StrokeDashArray="0 7.854"> 

<Path.Data 〉 

<E11ipseGeometry Radi usX="90" RadiusY="90" /> 
〈 /Path.Data 〉 

</Path> 


<!-- Hour hand pointing straight up --> 

〈Path Data="M 0 -6 C 0 -3, 2 -3, 0.5 -2 L 0.5 0 

C 0.5 0.75, —/5 0.75, -0.5 0 L -0.5-2 
C -2 -3, 0 -3, 0 -6" 

Stroke="{Bi nding El ementName=ctrl , Path=Foreg round}"> 
<Path.RenderTransform> 

<RotateTransform Angle="{Bi nding HourAngl e}" /> 
</Path.RenderTransform> 

</Path> 


<!-- Minute hand pointing straight up --> 

〈Path Data="M 0 -8 C 0 -7.5, 0 -7, 0.25 -6 L 0.25 0 

C 0.25 0.5, -0.25 0.5, -0.25 0 L -0.255 -6 
C 0 -7, 0 -7.5, 0 -8.0" 

Stroke="{Bi nding El ementName=ctrl , Path=Foreg round}"> 
<Path.RenderTransform> 

<RotateTransform Angle="{Binding MinuteAngl e} M /> 
</Path.RenderTransform> 

</Path> 
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<!-- Second hand pointing straight up --> 

<Path Data="M 0 1 L 0 -8" 

Stroke="{Bi nding El ementName=ctrl , Path=Foreg round}"> 
<Path.RenderTransform> 

<RotateTransform Angle="{Bi nding SecondAngl e}" /> 
</Path.RenderTransform> 

</Path> 

</Gri d> 


<Viewbox Grid. Row="2"> 

<TextBlock Text="{Bi nding FormattedDateTime}" /> 
</Viewbox> 

</Grid> 

</Viewbox> 

</Grid> 

</UserControl > 


Both TextBlock elements and all the RotateTronsform elements have bindings to properties in 
a view model. Toward the top of the TimeZoneClock.xaml file you'll see that this view model also 
includes properties of type Color named Foreground and Background. The code-behind file has 
nothing but a call to InitiolizeComponent. 

To keep this program relatively simple, I decided to limit the colors for the background and 
foreground of each clock to those 140 colors that have names and hence correspond to members 
of the static Colors class. The view model for the TimeZoneClock class defines Foreground and 
Background properties of type Color as you might expect, but it also defines ForegroundName and 
BackgroundName properties, and whenever one of these properties is changed, the other changes as 
well with a little reflection logic: 

Project: ClockRack | File: TimeZoneClockViewModel.es (excerpt) 

public class TimeZoneCIockViewModel : INotifyPropertyChanged 

{ 

string location = "New York City", timeZoneKey = "Eastern Standard Time" ; 

Color background = Colors .Yellow, foreground = Colors. Blue; 
string backgroundName = "Yellow" , foregroundName = ''Blue ”； 

DateTime dateTime; 

string formattedDateTime; 

double hourAngle, minuteAngle, secondAngle; 

Typelnfo colorsTypelnfo = typeof (Colors) .GetTypelnfoO; 

public event PropertyChangedEventHandler PropertyChanged; 

public string Location 

{ 

set { SetProperty<stri ng>(ref location, value); } 
get { return location; } 

} 

public string TimeZoneKey 

{ 

set { SetProperty<stri ng>(ref timeZoneKey, value); } 
get { return timeZoneKey; } 

} 
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public string BackgroundName 


set 

if (SetProperty<stri ng>(ref backgroundName, value)) 
this .Background = NameToColor(value); 

} 

get { return backgroundName; } 

} 

public Color Background 

{ 

set 

if (SetProperty<Col or>(ref background, value)) 
this .BackgroundName = ColorToName(val ue) ; 

} 

get { return background; } 

} 

public string ForegroundName 

{ 

set 

{ 

if (SetProperty<stri ng>(ref foregroundName, value)) 
this .Foreground = NameToColor(value); 

} 

get { return foregroundName; } 

} 

public Color Foreground 


set 

if (SetProperty<Color>(ref foreground, value)) 
this. ForegroundName = ColorToName(val ue) ; 

} 

get { return foreground; } 


public DateTime DateTime 


set 

if (SetPrope rty<DateTime>( ref dateTime, value)) 

{ 

this .FormattedDateTime = String .Format("{0:D} {1:t}" , value, value); 
this .SecondAngle = 6 * (dateTime.Second + dateTime.Mi 11isecond / 1000.0); 
this .MinuteAngle = 6 * dateTime.Minute + this .SecondAngle / 60; 
this .HourAngle = 30 * (dateTime.Hour % 12) + thi s. MinuteAngle / 12; 

} 

} 

get { return dateTime; } 


public string FormattedDateTime 
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} 


set { SetProperty<stri ng>(ref formattedDateTime, value); } 
get { return formattedDateTime; } 


public double HourAngle 

{ 

set { SetProperty<doubl e>(ref hourAngle, value); } 
get { return hourAngle; } 

} 

public double MinuteAngle 

{ 

set { SetProperty<doubl e>(ref minuteAngle, value); } 
get { return minuteAngle; } 

} 

public double SecondAngle 

{ 

set { SetProperty<doubl e>(ref secondAngle, value); } 
get { return secondAngle; } 

} 

Color NameToColor (string name) 

{ 

return (Color)colorsTypelnfo.GetDeclaredProperty(name) .GetValue(null) ; 

} 

string ColorToName(Col or color) 

{ 

foreach (Propertylnfo property in colorsTypelnfo.DeclaredProperties) 
if (color.Equals( (Colo r)property.GetValue (null))) 
return property.Name; 

return "" ; 

} 

protected bool SetProperty<T>(ref T storage, T value, 

[Cal 1 erMemberName] string propertyName = null) 

{ 

if (object .Equals(storage, value)) 
return false; 

storage = value; 

OnPropertyChanged(propertyName); 
return true; 

} 

protected void OnPropertyChanged(stri ng propertyName) 

{ 

if (PropertyChanged != null) 

PropertyChanged(thi s , new PropertyChangedEventArgs (propertyName)); 

} 

} 
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This view model also includes a DoteTime property, and whenever that changes, the HourAngle, 
MinuteAngle, and SecondAngle properties also change, driving the three RototeTransform objects in 
TimeZoneClock.xaml. 

To display multiple clocks, I wanted a type of panel that would allow all the clocks to be displayed 
within the confines of the page but that allocated optimum space for each child. The UniformGrid 
panel I developed in Chapter 11, "The Three Templates," seemed close to what I wanted but not 
exactly. For example, suppose there are seven clocks and the UniformGrid determines that they 
should be displayed in two rows of five clocks each. UniformGrid would put five clocks in the first row 
and two clocks in the second. It would be more aesthetically pleasing for the panel to distribute the 
clocks among the two rows more equally — four clocks in one row and three clocks in the other. 

The ClockRack program includes a reference to the Petzold.ProgrammingWindows6.Chapterll 
library from Chapter 11 but derives from UniformGrid a panel named DistributedUniformGrid. The 
logic in this new class allocates approximately an equal number of items to each row. Within each 
row, the items are equally spaced: 

Project: ClockRack I File: DistributedUniformGrid.es 

using System; 

using Windows.Foundation; 

using Windows.UI.Xaml.Controls; 

using Petzold.ProgrammingWindows6.Chapter'll; 


namespace ClockRack 
{ 

public cl ass Di stri butedllni formGri d : UniformGrid 
{ 

protected override Size ArrangeOverride(Si ze final Size) 

{ 

int index = 0; 

double cellWidth = finalSize.Width / cols; 
double cell Height = finalSize■Height / rows; 
int displayed =0; 

if (thi s .Orientation == Orientation .Vertical) 

{ 

for (int row = 0; row < rows; row++) 

{ 

double y = row * cell Height; 

int accumDisplay = (int) Math. Ceiling((row + 1.0) * 
this .Children.Count / rows); 
int display = accumDisplay - displayed; 
cellWidth = Math .Round(finalSize.Width / display); 
double x = 0; 

for (int col =0; col < display; col++) 

{ 

if (index < this .ChiIdren.Count) 

this .Children[index].Arrange (new Rect(x, y, cellWidth, cell Height)); 


x += cellWidth; 
index++; 


} 
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displayed += display; 

} 

} 

el se 

{ 

for (int col = 0; col < cols; col++) 

{ 

double x = col * cellWidth; 
int accumDisplay = 

(int)Math.CeilingC(col + 1.0) * thi s. Children.Count / cols); 
int display = accumDisplay - displayed; 
cell Height = Math. Round(finalSize.Height / display); 
double y = 0; 

for (int row = 0; row < display; row++) 

{ 

if (index < this .Children.Count) 

this .Children[index].Arrange (new Rect(x, y, cellWidth, cell Height)); 

y += cell Height; 
index++; 

} 

displayed += display; 

} 

} 

return final Size; 

} 

} 

} 


The MainPage.xaml file consists of little more than a DistributedUniformGrid to hold the clock 
controls: 


Project: ClockRack | File: MainPage.xaml (excerpt) 

<Page … > 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Grid Name="contentGrid" 

Background="Transparent"> 


<Di stributedllniformGrid Name="uni formGrid" 


</Crid> 
</Grid> 
</Page> 


Orientati on="Verti cal" /> 


The constructor of the Main Page class is responsible for populating the DistributedUniformGrid 
from application settings. The program uses the ApplicotionDato class in the Windows.Storage 
namespace for storing four text items per clock: the location name (selected by the user), the time 
zone key identifying the time zone for the clock, a foreground color name, and a background color 
name. For the first clock, these are stored using keys "OLocation”，"OTimeZoneKey", "OForeground”， 
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and "OBackground”; the second clock has keys that begin with the number 1, and so forth. As each set 
of settings is retrieved, a TimeZoneClock and TimeZoneClockViewModel are created and initialized: 

Project: ClockRack I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

■ _ _ 

IPropertySet appSettings = ApplicationData. Current.LocalSettings.Values; 

public MainPage() 

{ 

this. InitializeComponent(); 

// Load application settings for clocks 
int index = 0; 

while (appSettings.ContainsKey(index.ToString() + "Location")) 

{ 

string preface = index.ToString(); 

TimeZoneClock clock = new TimeZoneClock 

{ 

DataContext = new TimeZoneClockViewModel 

{ 

Location = appSettings[preface + "Location"] as string, 

TimeZoneKey = appSetti ngs[preface + "TimeZoneKey"] as string ， 

ForegroundName = appSettings[preface + "Foreground"] as string, 
BackgroundName = appSettings[preface + "Background"] as string 

}， 

}； 

uniformGrid.Children.Add(clock); 
index += 1; 

} 

// If there are no settings ， make a default Clock 
if (uniformGrid.Children.Count == 0) 

{ 

TimeZoneClock clock = new TimeZoneClock 

{ 

DataContext = new TimeZoneClockViewModel () 

}； 

uniformGrid.Children.Add(clock); 

} 

// Set the Suspending handler 

Application .Current.Suspend!ng += OnApplicationSuspending; 

// Start the Rendering event 

CompositionTarget .Rendering += OnCompositionTargetRendering; 
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void OnApplicationSuspending (object sender, SuspendingEventArgs args) 

{ 

appSettings.Clear(); 


for (i nt index = 0; index < uni formOid. Children .Count; i ndex++) 

{ 

TimeZoneCl ock timeZoneClock = uni formGHd. Children [index] as TimeZoneClock; 
TimeZoneClockViewModel viewModel = 

timeZoneClock.DataContext as TimeZoneClockViewModel ; 
string preface = index.ToString(); 


appSettings[preface 
appSettings[preface 
appSettings[preface 
appSettings[preface 


+ "Location"] = viewModel.Location; 

+ "TimeZoneKey"] = viewModel.TimeZoneKey; 

+ "Foreground"] = viewModel.ForegroundName; 
+ "Background"] = viewModel.BackgroundName; 


As usual, these settings are saved during the Suspending event. 


The constructor concludes by starting up a CompositionTarget.Rendering event. This is responsible 
for using the TimeZoneManoger instance to obtain a local time based on the current UTC time with 
the time zone key for each clock: 


Project: ClockRack I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

TimeZoneManager timeZoneManager = new TimeZoneManagerO ; 

■ ■ ■ 

void OnCompositionTargetRenderi ng(object sender, object args) 

{ 

// Get the time once 
DateTime utc = DateTime .UtcNow; 

foreach (UIE1 ement child in uniformGHd.Children) 

{ 

TimeZoneClockViewModel viewModel = 

(child as FrameworkEl ement) .DataContext as TimeZoneClockViewModel ; 

string timeZoneKey = viewModel.TimeZoneKey; 

// Set the local time from the TimeZoneManager 

viewModel.DateTime = timeZoneManager.GetLocalTime(timeZoneKey, utc); 



} 


A right tap displays a PopupMenu with three items: Add, Edit, and Delete. The Edit and Delete 
items pertain to the particular clock being tapped, so the OnRightTapped override begins by finding 
that tapped clock. That object is passed to the handlers for these three items. Even for Add, the 
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tapped clock is needed because the logic inserts the new clock after that tapped clock. The Delete 
item appears on the menu only if there’s more than one clock: 

Project: ClockRack I File: MainPage.xaml.es (excerpt) 

async protected override void OnRightTapped(Ri ghtTappedRoutedEventArgs args) 

{ 

// Check if the parent of the click element is a TimeZoneClock 
FrameworkElement element = args.OriginalSource as FrameworkElement ; 


while (element != null) 

{ 

if (element is TimeZoneClock) 
break; 

element = element.Parent as FrameworkElement ; 

} 

if (element == null) 
return ; 

// Create a PopupMenu 

PopupMenu popupMenu = new PopupMenu (); 

popupMenu.Commands .Add(new UICommand("Add ..." , OnAddMenuItem, element)); 
popupMenu.Commands .Add(new UICommand("Edi t.. OnEditMenuItem, element)); 

if (uniformGrid.Children.Count >1) 

popupMenu.Commands .Add(new UICommand("Del ete" , OnDeleteMenuItem, element)); 

args.Handled = true ; 
base. OnRightTapped(args); 


// Display the menu 

await popupMenu.ShowAsync(args.GetPosition (this)); 


For the Add menu item, a new TimeZoneClock (with a corresponding TimeZoneClockViewModel) 
must be created and inserted into the collection. This new clock is always inserted after the clock that 
was tapped: 


Project: ClockRack I File: MainPage.xaml.es (excerpt) 

void OnAddMenuItemCIUICommand command) 

{ 

// Create new TimeZoneClock 

TimeZoneClock timeZoneClock = new TimeZoneClock 

{ 

DataContext = new TimeZoneClockViewModel () 

}； 

// Insert after the tapped clock 

TimeZoneClock clickedClock = command.Id as TimeZoneClock; 

int index = uniformGrid.Chi 1dren.IndexOf(clickedClock); 
uniformGrid.Children.Insert(index + 1, timeZoneClock); 
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The Delete item is also fairly easy, but the program insists on getting a confirmation of the deletion 
using a MessogeDiolog: 

Project: ClockRack I File: MainPage.xaml.es (excerpt) 

async void OnDel eteMenuItemCIUICommand command) 

{ 

TimeZoneClock timeZoneClock = command.Id as TimeZoneClock; 

TimeZoneClockViewModel vi ewModel = timeZoneClock.DataContext as TimeZoneClockViewModel ; 

MessageDialog msgdlg = new MessageDialogC'Delete clock from collection?" , 

viewModel.Location); 

msgdlg.Commands.Add (new UICommand("OK "))； 
msgdlg.Commands.Add (new UlCommandC" Cancel ")) ； 
msgdlg.DefaultCommandlndex = 0; 
msgdlg.CancelCommandlndex = 1; 

IUICommand msgDlgCommand = await msgdlg.ShowAsyncC); 

if (msgDlgCommand.Label == "OK") 

uniformGrid.Children.Remove(command.Id as TimeZoneClock) ; 

} 


Of course, the Edit option is more involved, and unless you’re entirely satisfied with a clock for New 
York City with a blue foreground on a yellow background, you’re going to be invoking the Edit menu 
right after you add a new clock. The Edit option instantiates a SettingsDialog (which you'll see shortly) 
as a child of a Popup object. Because SettingsDialog needs to access the TimeZoneMonager instance, 
the TimeZoneMonager object is supplied to the SettingsDialog constructor. The bulk of this method 
is responsible for positioning the Popup so that it is visually associated with the tapped clock but 
doesn’t hang off the edge of the screen: 


Project: ClockRack | File: MainPage.xaml.es (excerpt) 

void OnEditMenuItemCIUICommand command) 

{ 

TimeZoneClock timeZoneClock = command.Id as TimeZoneClock; 
SettingsDialog SettingsDialog = new Setti ngsDialog(timeZoneManager); 
SettingsDialog.DataContext = timeZoneClock.DataContext; 

// Create Popup with SettingsDialog child 
Popup popup = new Popup 
{ 

Child = SettingsDialog, 

IsLightDismissEnabled = true 

}； 


settingsDialog.SizeChanged += (sender, args)=> 

{ 

// Get clock center 

Point position = new Poi nt(timeZoneClock.ActualWidth / 2 ， 

timeZoneClock.ActualHeight / 2); 

// Convert to Page coordinates 

position = timeZoneClock.TransformToVisual (this) .TransformPoint(position); 
// Position popup so lower-left or lower-right corner 
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// aligns with center of edited clock 

if (position.X > this .ActualWidth / 2) 

position.X -= settingsDialog.ActualWidth; 
position.Y -= settingsDialog.Actual Height; 


// Adjust for size of page 

if (position.X + settingsDialog.ActualWidth > this .ActualWidth) 
position.X = this .ActualWidth - settingsDialog•ActualWidth; 


if (position.X < 0) 
position.X = 0; 


if (position.Y < 0) 
position.Y = 0; 


// Set the Popup position 

popup.HorizontalOffset = position.X; 

popup.Vertical Offset = position.Y; 


popup.IsOpen = true; 

} 


Here’s what the SettingsDiolog looks like. The first field is an EditBox that simply allows you to type 
in a label; the other three fields use a ComboBox to display the currently selected item. The ComboBox 
opens up to display a list of items when the control receives input focus: 


ClockRack settings for 
London 


New York City 




Thursday, November 8, 2012 1:04 PM Thursday, November 8, 2012 12:04 PM Thursday, November 8, 2012 10:04 AM 



The DataContext of the SettingsDiolog object is set to the Data Context of the TimeZoneClock being 
edited. That DataContext property is an object of TimeZoneClockViewModel, and the XAML file has 
bindings to the Location, TimeZoneKey, ForegroundNome, and BackgroundName properties of that 
class. Notice that the TextBox bound to the Location property has its TextChanged event set; this 
allows the code-behind file to update the Location property in TimeZoneClockViewModel "manually," 
which then updates the display at the top of the popup. 
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Project: ClockRack I File: SettingsDialog.xaml (excerpt) 


<UserControl … > 

<UserControl.Resources 〉 

<Style x : Key="Di alogCaptionTextStyle" 

TargetType="Text Block" 

BasedOn="{Stati cResource CaptionTextStyl e}"> 
〈Setter Property="FontSi ze" Value="14.67" /> 
〈Setter Property="FontWei ght" Val ue="Semi Light" /> 
〈Setter Property="Margi n" Value="0 16 0 8" /> 
</Style> 


<DataTemplate x:Key="col orltemTemplate"> 

<!-- Item is SettingsDialog.Colorltem --> 

<StackPanel Orientati on="Hori zontal"> 

〈Rectangle Wi dth="96" Hei ght="24" Margi n="12 6"> 
<Rectangle.Fi11 > 

<SolidColorBrush Color="{Binding Color}" /> 
</Rectangle.Fi11 > 

</Rectangle> 


<TextBlock Text="{Binding Name}" 

VerticalAli gnment="Center" /> 

</StackPanel> 

</DataTemplate> 

</UserControl.Resources 〉 


<!-- DataContext is TimeZoneClockViewModel --> 

〈Border Background="{Stati cResource ApplicationPageBackgroundThemeBrush}" 
BorderBrush="{Stati cResource ApplicationForegroundThemeBrush}" 
BorderThi ckness="l" 

Padding="7 0 0 0" 

Width="384"> 

<StackPanel Margi n="24"> 

<TextBlock Text="ClockRack settings for" 

Styl e="{StaticResource SubheaderTextStyl e}" 

TextAli gnment="Center" /> 

<TextBlock Text="{Bindi ng Location} 11 

Styl e="{StaticResource SubheaderTextStyl e}" 

TextAli gnment="Center" 

Margi n="0 0 0 12" /> 

<!-- Location --> 

<TextBlock Text="Locati on" 

Styl e="{StaticResource DialogCaptionTextStyl e}" /> 

cTextBox Name="locati onTextBox" 

Text="{Binding Location}" 

TextChanged="OnLocati onTextBoxTextChanged" /> 

<!-- Time Zone --> 

〈TextBlock Text="Ti me Zone" 

Styl e="{StaticResource DialogCaptionTextStyl e}" /> 

cComboBox Name="ti meZoneComboBox" 

SelectedVal uePath="TimeZoneKey" 
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SelectedVal ue="{Binding TimeZoneKey, Mode=TwoWay}"> 
<ComboBox.ItemTemplate> 

<!-- Data is TimeZoneDisplaylnfo --> 

<DataTemplate> 

<TextBlock Text="{Binding Display}" /> 

</DataTemplate> 

</ComboBox.ItemTempl ate> 

</ComboBox> 


<!-- Foreground and Background Colors --> 

<TextBlock Text=" Foreground Color" 

Styl e="{StaticResource DialogCaptionTextStyle}" /> 

cComboBox Name="foregroundComboBox" 

ItemTempl ate="{StaticResource colorltemTempl ate}" 

SelectedVal uePath="Name" 

SelectedVal ue="{Binding ForegroundName , Mode=TwoWay}" /> 

<TextBlock Text=" Background Color" 

Style="{StaticResource DialogCaptionTextStyle}" /> 

<ComboBox Name="backgroundComboBox" 

ItemTempl ate="{StaticResource colorltemTempl ate}" 

SelectedVal uePath="Name" 

SelectedVal ue="{Binding BackgroundName , Mode=TwoWay}" /> 

</StackPanel> 

</Border> 

</UserControl > 


The code-behind file (shown next) supplies collections for the three ComboBox controls. The 
ComboBox for the time zone is filled from the Disploylnformotion property of the TimeZoneMonager, 
and the markup for that first ComboBox references the TimeZoneKey and Display properties. 

Because I was already using the Petzold.ProgrammingWindows6.Chapterll library for 
UniformGrid, I decided to use the NamedColor class to get a collection of NamedColor objects. As 
you can see in the XAML file, the ItemTemplate used for those two ComboBox controls references the 
Color and Nome properties of NamedColor, and each ComboBox indicates that the SelectedVoluePath 
is the Name property. 

Project: ClockRack I File: SettingsDialog.xaml.es (excerpt) 

public sealed partial class SettingsDialog : UserControl 

{ 

public SettingsDi alog(TimeZoneManager timeZoneManager) 

{ 

this .InitializeComponent(); 

// Set ItemsSource for time zone ComboBox 

timeZoneComboBox.ItemsSource = timeZoneManager.Displaylnformation; 

// Set ItemsSource for foreground and background ComboBoxes 
foregroundComboBox.ItemsSource = NamedColor. All; 
backgroundComboBox.ItemsSource = NamedColor. All; 

} 
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void OnLocationTextBoxTextChanged (object sender, TextChangedEventArgs args) 

{ 

(this .DataContext as TimeZoneClockViewMode! ).Location = (sender as TextBox) .Text; 

} 


That concludes the code for ClockRack. 


A Windows Runtime Component Wrapper for DirectX 

While P/Invoke is fine for accessing various functions in the flat Win32 API, getting at DirectX is a 
different matter. DirectX is a bit awkward for P/Invoke and is best accessed from C++ code. If you 
want to use DirectX from a C# program, you can write a Windows Runtime Component in C++ 
containing all the DirectX code and then access that library from the C# program. For some small 
areas of DirectX, you might do this on your own, or you can pursue a more extensive solution such as 
the open-source SharpDX library available at http://code.google.eom/p/sharpdx. 

However, you might ponder if you are deceiving yourself in some way by accessing DirectX from a 
C# program through a wrapper library. One reason to use DirectX is for performance, and often that 
involves not only the performance of the DirectX library itself (which is independent of the language 
using it) but the performance of your application code. Your application code will generally run faster 
if it’s coded in C++ rather than C# (even though you might code faster and with fewer errors using 
C#). Consequently, you might want to make the choice to code some or all of your DirectX application 
in C++. 

The DirectXWrapper library I’ll be presenting here is extremely sparse. I’ve deliberately limited it 
to three specific jobs: obtaining a list of fonts installed on the system, obtaining font metrics for a 
particular font, and drawing lines on a SurfacelmogeSource object. This SurfacelmageSource is actually 
a bitmap except you don’t have to implement your own line-drawing algorithms as I did in Chapter 
14, "Bitmaps." 

To create this library in Visual Studio, I made a new solution and project named DirectXWrapper. 

In the left column of the New Project dialog box, I specified that it was a C++ Windows Store project. 
The template I chose in the central area of the dialog box was Windows Runtime Component. This 
is a type of Windows 8 library that can be coded in one language (C++ in this case) and accessed 
from any other Windows Store application, including those written in C#, Visual Basic, and JavaScript. 
Because of this flexibility, Windows Runtime Components have very stringent limitations. They can’t 
do something that’s foreign to one of these languages. 

The most significant of the limitations of a Windows Runtime Component are these: 

■ Public classes must be sealed or non-instantiable. 

■ Parameters and return values of public methods must be Windows Runtime types. 

■ Public C++ classes and structures must be defined as ref (meaning reference counted). 

■ Public members of structures are restricted to fields. 

808 PART Specialties 



Other limitations are described in the Windows 8 documentation. (Do a search for "Creating Windows 
Runtime Components .’’） 

This DirectXWrapper project needs to reference some C++ libraries not included by default. In the 
Solution Explorer, I right-clicked the project name and selected Properties. A dialog appears entitled 
DirectXWrapper Property Pages. At the top of the dialog is a Platform combo box. In this I selected 
All Platforms. At the left of the dialog I selected Configuration Properties, Linker, and Input. At the top 
of the resultant list of items is a field titled Additional Dependencies. Click that field and select Edit. 
You’ll see an Additional Dependencies dialog box. To the list I added three DirectX libraries: 

■ d2dl.lib 

■ d3dll.lib 

■ dwrite.lib 

The first two of these are for 2D and 3D graphics and are required for drawing on a 
SurfocelmogeSource. The third is the library for DirectWrite. 

The DirectXWrapper library also requires accessing some header files associated with these 
libraries. In the pch.h ("precompiled headers” ） file, I included the required header files: 


Project: DirectXWrapper I File: pch.h 
#pragma once 


#i nclude <wrl.h> 

#include <d2dl_l.h> 

#include <d3dll_l.h> 

#i nclude <dwrite.h> 

#i nclude <wi ndows.ui.xaml.media.dxi nterop.h> 

The wrl.h header file stands for "Windows Runtime Library” and contains definitions useful for 
working with COM in Windows 8 applications. The windows.ui.xaml.media.dxinterop.h header file has 
a declaration for the ISurfocelmogeSourceNotive interface required for using the SurfocelmogeSource 
class. 


DirectWrite and Fonts 


DirectWrite is the subset of DirectX dedicated to the high-performance display of text. Even if you 
don’t need that performance, DirectWrite provides a couple facilities missing from the Windows 
Runtime, specifically obtaining a list of installed fonts and obtaining font metrics. 

For accessing DirectWrite, I decided that I would define classes in my DirectXWrapper library in a 
one-to-one correspondence with DirectWrite interfaces. These interfaces all begin with ID Write: The 
/is for "interface" and D Write is for "DirectWrite." My corresponding classes simply begin with Write. 
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This is bound to be a little confusing at first, but here’s the correspondence in the order I’ll be 
discussing them: 


DirectWrite Interface 

DirectXWrapper Class 

IDWriteFactory 

WriteFactory 

IDWriteFontCollection 

WriteFontCollection 

IDWriteFontFamily 

WriteFontFamily 

IDWriteFont 

WriteFont 

IDWriteLocalizedString 

WriteLocalizedStrings 


In many cases, method names in the DirectWrite interfaces (for example, the GetMetrics method 
in IDWriteFont) have simply been duplicated: My Write Font class also has a GetMetrics method. I have 
not attempted to duplicate oil the methods in these interfaces. 

A program that wishes to use DirectWrite begins by calling the DWriteCreateFactory function to 
obtain an object of type IDWriteFoctory. Among many other methods, this IDWriteFactory interface 
defines GetSystemFontCollection for obtaining the fonts currently installed on the system. 


I wrapped IDWriteFoctory in my own class named WriteFoctory. Here’s the C++ header file: 


Project: DirectXWrapper | File: WriteFactory.h 

#pragma once 

#i nclude "WriteFontCol 1ection.h" 


namespace DirectXWrapper 
{ 

public ref class WriteFactory sealed 
{ 

private: 

Microsoft: : WRL :: ComPtr<IDWriteFactory> pFactory; 
public: 

WriteFactory(); 

Wri teFontCol 1 ecti onA GetSystemFontCollectionO ; 

WriteFontCol1ecti onA GetSystemFontCollection (bool checkForUpdates); 

}； 

} 

The class is defined with ref and sealed, which is required for public C++ classes in a Windows 
Runtime Component. The ref indicates that the class must be instantiated with ref new rather than just 
new, and the constructor returns a reference-counted handle rather than a pointer. 

The IDWriteFoctory object obtained from DWriteCreateFactory is stored as a private field as a 
ComPtr, which is defined in the Microsoft.Wrl namespace (or Microsoft::WRL namespace using C++ 
syntax). ComPtr is short for "Common Object Model pointer" — it turns a pointer to a COM object 
such as IDWriteFoctory into a "smart pointer" that is reference counted and that properly releases its 
own resources. This is the recommended way to maintain pointers to COM objects in your Windows 8 
DirectX code. 
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Three public methods are also defined in the header file: a constructor and two versions of a 
GetSystemFontCollection method. These methods return a WriteFontCollection object. This is not a 
DirectWrite type. It can’t be because public methods in a Windows Runtime Component can return 
Windows Runtime types only. Instead, it is another class in the DirectXWrapper library. The hat ( A ) 
means that WriteFontCollection is a handle rather than a pointer, which means that it’s also defined 
with the ref keyword and instantiated in C++ with ref new rather than just new. 

The mention of the WriteFontCollection class in this header file requires the inclusion of the 
WriteFontCollection.h header file at the top. 

The implementation of the WriteFactory class is in the WriteFactory.cpp file: 


Project: DirectXWrapper | File: WriteFactory.cpp 

#include "pch.h" 

#include "WriteFactory.h" 

using namespace DirectXWrapper; 
using namespace Platform; 
using namespace Microsoft : : WRL; 

WriteFactory: : WriteFactoryC) 

{ 

HRESULT hr = DWriteCreateFactory(DWRITE_FACTORY_TYPE_SHARED, 

— uuidof (IDWriteFactory) , 
«&pFactory); 


} 


if (!SUCCEEDED(hr)) 

throw ref new COMException(hr) ; 


WriteFontCol1ecti onA Wri teFactory: : GetSystemFontCol1ection() 
{ 

return GetSystemFontCollection(false); 

} 


WriteFontCollectionA WriteFactory: : GetSystemFontCollection (bool checkForUpdates) 

{ 

ComPtr<IDWriteFontCol1ecti on> pFontCol1ection; 

HRESULT hr = pFactory->GetSystemFontCol1ection(&pFontCol1ection, checkForUpdates); 

if (!SUCCEEDED(hr)) 

throw ref new COMException(hr) ; 

return ref new WriteFontCol1ecti onCpFontCol1ecti on); 

} 

The constructor calls the DWriteCreateFoctory function to obtain the IDWriteFoctory object. The 
一 — uu id of operator obtains a GUID identifying this object. Very often DirectX functions and methods 
return values of type HRESULT. This is simply a number indicating success or failure, but it’s important 
not to ignore them. The standard approach in a Windows 8 program is to raise an exception of type 
COMException if an error has occurred. Notice the ref new used to instantiate that COMException 
class; that’s a Windows Runtime type. 


CHAPTER 15 Going Native 


811 


The GetSystemFontCollection method in my Write Factory class uses the l DWrite Factory object 
to call the GetSystemFontCollection method of that interface to obtain a pointer to a DirectWrite 
IDWriteFontCollection interface. This is passed to the WriteFontCollection constructor. Again, notice 
the ref new. 

Here’s the WriteFontCollection header file: 


Project: DirectXWrapper I File: WriteFontCollection.h 

#pragma once 


#include "WriteFontFamily.h" 


namespace DirectXWrapper 

{ 

public ref class WriteFontCol1ection sealed 

{ 

private: 

Microsoft: : WRL :: ComPtr<IDWriteFontCol1ecti on> pFontCol1ection; 
internal : 

WriteFontCol1ection(Microsoft: : WRL: : ComPtr<IDWriteFontCol1ection> pFontCol1ection); 
public: 

bool FindFami1yName(Platform :: Stri ngA familyName, int * index); 
int GetFontFamilyCountC); 

WriteFontFami1 yA GetFontFami1 y (i nt index); 

}； 

} 

The constructor is defined as internal to the library. It can’t be private because then it couldn’t be 
accessed from outside the class (and obviously the WriteFontFactory class needs to call it). But it can't 
be public because the constructor argument is not a Windows Runtime type. Also notice the use of 
the String class defined in the Platform namespace. This String class is a Windows Runtime type, and it 
is equivalent to the C# String class defined in the System namespace. 

Here’s the implementation of WriteFontCollection: 


Project: DirectXWrapper I File: WriteFontCollection.cpp 
#include "pch.h" 

#include "WriteFontCol1ection.h" 

#include "WriteFontFamily.h" 

using namespace DirectXWrapper; 
using namespace PI atform; 
using namespace Microsoft :: WRL; 

WriteFontCol1ecti on: : WriteFontCol1ection (ComPtr<IDWriteFontCol1ection> pFontCol1ection) 

{ 

thi s->pFontCol1ection = pFontCollection; 

} 


bool WriteFontCollection: :FindFamilyName (StringA familyName, int * index) 

{ 

uint32 familylndex; 
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BOOL exists; 

HRESULT hr = thi s->pFontCol 1 ection->Fi ndFami 1 yName(fami 1 yName->Data() ,&fami 1 ylndex,&exi sts); 

if (!SUCCEEDED(hr)) 

throw ref new COMException(hr) ; 

*index = familylndex; 

return exists != 0; 

} 

int WriteFontCol1ection :: GetFontFami1yCount() 

{ 

return pFontCol1ection->GetFontFami1yCount(); 

} 

WriteFontFami 1 yA WriteFontCol1ection :: GetFontFami ly(i nt index) 

{ 

ComPtr<IDWriteFontFami1 y> pfontFamily; 

HRESULT hr = pFontCol1ection->GetFontFami1y(index, &pfontFamily); 

if (!SUCCEEDED(hr)) 

throw ref new COMException(hr) ; 

return ref new WriteFontFamily (pfontFamily); 

} 

Obtaining a particular font family from this collection is a two-step process. First, FindFomilyName 
must be called with a particular name (such as "Times New Roman") to obtain an index within the 
collection. That index is then passed to GetFontFamily to obtain an IDWriteFontFomily object (when 
using DirectWrite) or a WriteFontFamily object (when using the DirectXWrapper library). 

Alternatively, all the fonts in the collection can be enumerated by passing indices to GetFontFamily 
up to the value returned from GetFontFomilyCount. 

Here's the Wri te Fon t Family header file: 

Project: DirectXWrapper | File: WriteFontFamily.h 

#pragma once 

#i nclude "WriteLocalizedStrings. h" 

#include "WriteFont.h" 

namespace DirectXWrapper 

{ 

public ref class WriteFontFamily sealed 

{ 

private: 

Microsoft: : WRL :: ComPtr<IDWriteFontFami 1 y> pFontFamily; 
internal : 

WriteFontFamily(Microsoft: : WRL :: ComPtr<IDWriteFontFami 1 y> pFontFamily); 
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} 


public: 

WriteLocalizedStringsA GetFami1yNames(); 

WriteFontA GetFirstMatchingFont(Windows : : UI: : Text: : FontWeight fontWeight, 

Windows::UI: : Text: : FontStretch fontStretch, 
Windows::UI: : Text :: FontStyle fontStyle); 


}； 


Look at those arguments to GetFirstMotchingFont: Those are Windows Runtime types because 
they're defined in the Windows.Ul.Text namespace. FontWeight is a structure, which is the type of the 
static properties in the FontWeights class, and FontStretch and FontStyle are both enumerations. In 
the Get Firs tMo tching Font method implemented by the ID WriteFontFamily interface, the arguments 
are of type DWRITE_FONT_WEIGHT, DWRITE_FONT_STRETCH, and DWRITE_FONT_STYLE, all of which 
are enumerations. Interestingly, the FontStretch and FontStyle values can be converted directly: The 
two enumerations have the same values, strongly indicating that DirectWrite forms the foundation of 
Windows Runtime text output. 


Project: DirectXWrapper | File: WriteFontFamily.cpp 

#include "pch.h" 

#include "WriteFontFamily.h" 

using namespace DirectXWrapper; 
using namespace Platform; 
using namespace Microsoft: : WRL; 
using namespace Windows::UI::Text; 

WriteFontFami ly: : WriteFontFami 1y(ComPtr<IDWri teFontFami1 y> pFontFamily) 

{ 

thi s->pFontFami1y = pFontFamily; 

} 

WriteLocalizedStringsA WriteFontFami1y :: GetFami1yNames() 

{ 

ComPtr<IDWriteLocalizedStrings> pFami1yNames; 

HRESULT hr = pFontFami1y->GetFami1yNamesC&pFami1yNames); 

if (!SUCCEEDED(hr)) 

throw ref new COMException(hr) ; 

return ref new WriteLocalizedStrings (pFami1yNames); 

} 

WriteFontA WriteFontFami1y :: GetFirstMatchingFont (FontWei ght fontWeight, 

FontStretch fontStretch, 
FontStyle fontStyle) 

{ 

// Convert font weight from Windows Runtime to DirectX 
DWRITE_FONT_WEIGHT writeFontWeight = DWRITE_FONT_WEIGHT_NORMAL; 
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if (fontWeight.Equals (FontWei ghts :: Black)) 

writeFontWeight = DWRITE_FONT_WEIGHT_BLACK; 

else if (fontWeight.Equals (FontWei ghts :: Bold)) 
writeFontWeight = DWRITE_FONT_WEIGHT_BOLD; 


else if (fontWeight.Equals (FontWei ghts :: ExtraBlack)) 
writeFontWeight = DWRITE_FONT_WEIGHT_EXTRA_BLACK; 


else if (fontWeight.Equals(FontWei ghts :: ExtraBold)) 
writeFontWeight = DWRITE_FONT_WEIGHT_EXTRA_BOLD; 


else if (fontWeight.Equals(FontWei ghts :: ExtraLight)) 
writeFontWeight = DWRITE_FONT_WEIGHT_EXTRA_LIGHT; 

else if (fontWeight■Equals (FontWei ghts ::Light)) 
writeFontWeight = DWRITE_FONT_WEIGHT_LIGHT; 

else if (fontWeight.Equals (FontWei ghts :: Medium)) 
writeFontWeight = DWRITE_FONT_WEIGHT_MEDIUM; 

else if (fontWeight.Equals(FontWei ghts :: Normal)) 
writeFontWeight = DWRITE_FONT_WEIGHT—NORMAL; 

else if (fontWeight.Equals(FontWei ghts :: Semi Bold)) 
writeFontWeight = DWRITE_FONT_WEIGHT_SEMI_BOLD; 


else if (fontWeight.Equals(FontWei ghts :: Semi Li ght)) 
writeFontWeight = DWRITE_FONT_WEIGHT_SEMI_LIGHT; 


else if (fontWeight.Equals (FontWeights :: Thin)) 
writeFontWeight = DWRITE_FONT_WEIGHT_THIN; 


// Convert font stretch from Windows Runtime to DirectX 
DWRITE_FONT_STRETCH writeFontStretch = (DWRITE_FONT_STRETCH) fontStretch; 


// Convert font style from Windows Runtime to DirectX 
DWRITE_FONT_STYLE writeFontStyle = (DWRITE_FONT_STYLE)fontStyl e; 


ComPtr<IDWriteFont> pWriteFont = nullptr; 

HRESULT hr = pFontFami1y->GetFirstMatchingFont(writeFontWeight, 

writeFontStretch, 
writeFontStyle, 
&pWriteFont); 

if OSUCCEEDED(hr)) 

throw ref new COMException(hr) ; 


return ref new Wri teFont(pWriteFont); 

} 


A font family usually has a name such as "Times New Roman," but in DirectWrite a font family can 
have several names that are specific to different locales and languages. The GetFamilyNomes method 
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returns not one name but a collection of names stored in an IDWriteLocolizedStrings. These strings are 
identified by standard locale names — for example, "e 门 -us" for United States English: 


Project: DirectXWrapper I File: WriteLocalizedStrings.h 

#pragma once 


namespace DirectXWrapper 

{ 

public ref class WriteLocalizedStrings sealed 

{ 

private: 

Microsoft: : WRL :: ComPtr<IDWriteLocalizedStri ngs> pLocalizedStrings; 
internal : 

WriteLocalizedStrings(Microsoft :: WRL :: ComPtr<IDWriteLocalizedStri ngs> 

pLocalizedStrings); 

public: 

i nt GetCountO ; 

PIatform: : Stri ngA GetLocaleName(i nt index); 

PIatform: : Stri ngA GetStri ng(i nt index); 

bool FindLocaleName(Platform :: Stri ngA localeName, int * index); 

}； 

} 


Here’s the implementation: 


Project: DirectXWrapper | File: WriteLocalizedStrings.cpp 
#include "pch.h" 

#i nclude "WriteLocalizedStri ngs.h" 

using namespace DirectXWrapper; 
using namespace Platform; 
using namespace Microsoft: : WRL; 

WriteLocalizedStrings :: WriteLocalizedStri ngs(ComPtr<IDWri teLocalizedStrings> pLocalizedStrings) 

{ 

thi s->pLocalizedStrings = pLocalizedStrings; 

} 

i nt Wri teLocal i zedStri ngs : : GetCountO 

{ 

return thi s->pLocalizedStrings->GetCount(); 

} 

StringA WriteLocalizedStrings :: GetLocaleName(i nt index) 

{ 

UINT32 length = 0; 

HRESULT hr = thi s->pLocalizedStrings->GetLocaleNameLength(index, &1ength); 


if OSUCCEEDED(hr)) 

throw ref new COMException(hr) ; 
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wchar_t* str = new (std :: nothrow) wchar_t [length + 1]; 
if (str == nul1 ptr) 

throw ref new COMException(E_OUTOFMEMORY) ; 

hr = thi s->pLocalizedStrings->GetLocaleName(index, str, length + 1); 

if (!SUCCEEDED(hr)) 

throw ref new COMException(hr) ; 

Stri ngA string = ref new Stri ng(str); 
delete[] str; 
return string; 

} 

StringA WriteLocalizedStrings :: GetString(i nt index) 

{ 

UINT32 length = 0; 

HRESULT hr = thi s->pLocalizedStrings->GetStringLength(index, &length); 

if (!SUCCEEDED(hr)) 

throw ref new COMException(hr) ; 

wchar_t* str = new (std :: nothrow) wchar_t [length + 1]; 

if (str == nul1 ptr) 

throw ref new C0MException(E_0UT0FMEM0RY) ; 

hr = thi s->pLocalizedStrings->GetString(index, str, length + 1); 

if (!SUCCEEDED(hr)) 

throw ref new COMException(hr) ; 

Stri ngA string = ref new Stri ng(str); 
delete[] str; 
return string; 

} 

bool WriteLocalizedStrings :: FindLocaleName(Stri ngA localeName, int * index) 

{ 

uint32 localelndex = 0; 

BOOL exists = false; 

HRESULT hr = thi s->pLocalizedStrings->FindLocaleName(localeName->Data(), 

&localeIndex, &exists); 

if (!SUCCEEDED(hr)) 

throw ref new COMException(hr) ; 

*index = localelndex; 

return exists != 0; 

} 
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Much of the "messiness" in this code involves allocating C++ strings (which are really arrays of 
characters) for calling the DirectWrite methods, and then converting to Windows Runtime String 
objects for returning from the DirectXWrapper implementation. 

Here’s the Write Font header file: 

Project: DirectXWrapper I File: WriteFont.h 

#pragma once 

#i nclude "WriteFontMetrics.h" 


namespace DirectXWrapper 

{ 

public ref class WriteFont sealed 

{ 

private: 

Microsoft: : WRL :: ComPtr<IDWriteFont> pWriteFont; 
internal : 

WriteFont(Microsoft :: WRL: : ComPtr<IDWriteFont> pWriteFont); 
public: 

bool HasCharacter(UINT32 unicodeValue); 
bool IsSymbolFont(); 

WriteFontMetrics GetMetrics(); 

}； 

} 


And the implementation: 


Project: DirectXWrapper I File: WriteFont.cpp 

#include "pch.h" 

#i nclude "WriteFont.h" 

using namespace DirectXWrapper; 
using namespace Platform; 
using namespace Microsoft :: WRL; 

WriteFont: :WriteFont (ComPtr<IDWriteFont> pWriteFont) 

{ 

thi s->pWriteFont = pWriteFont; 

} 

WriteFontMetrics WriteFont: : GetMetrics() 

{ 

DWRITE—FONT_METRICS fontMetrics; 

thi s->pWriteFont->GetMetrics(&fontMetri cs); 

WriteFontMetrics writeFontMetrics = 

{ 

fontMetrics.designUnitsPerEm, 
fontMetrics.ascent, 
fontMetrics.descent, 
fontMetrics.1ineGap, 
fontMetrics.capHeight, 
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fontMetrics.xHeight ， 
fontMetrics.underlinePosition, 
fontMetrics.underlineThickness, 
fontMetrics.strikethroughPosition, 
fontMetrics.strikethroughThickness 

}； 

return writeFontMetrics; 

} 

bool WriteFont: : HasCharacter(UINTB2 unicodeValue) 

{ 

BOOL exists = 0; 

HRESULT hr = thi s->pWriteFont->HasCharacter(unicodeValue, &exists); 

if (!SUCCEEDED(hr)) 

throw ref new COMException(hr) ; 

return exists != 0; 

} 

bool WriteFont: :IsSymbolFont() 

{ 

return thi s->pWriteFont->IsSymbolFont() != 0; 


The DirectWrite version of the Get Metrics method fills in a structure of type 
DWRITE_FONT_METRICS. Of course, a Windows Runtime Component can't return that directly, so I 
defined my own version of this structure: 

Project: DirectXWrapper I File: WriteFontMetrics.h 

#pragma once 


namespace DirectXWrapper 

{ 

public value struct WriteFontMetrics 

{ 

UINT16 Desi gnllni tsPerEm; 

UINT16 Ascent; 

UINT16 Descent; 

INT16 LineGap; 

UINT16 CapHeight; 

UINT16 XHeight; 

INT16 UnderlinePosition; 

UINT16 UnderlineThickness; 

INT16 StrikethroughPosition; 
UINT16 StrikethroughThickness; 

}； 

} 


You have now seen all the DirectWrite code implemented in the DirectXWrapper library. Obviously, 
there is much more to DirectWrite than what IVe attempted to make available to a C# program, but I 
now have what I need for two basic jobs. 
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Let’s enumerate the installed fonts. The EnumerateFonts project is a normal Windows 8 C# project, 
except that in the Solution Explorer I right-clicked the solution name and selected Add and Existing 
Project. The project I added was DirectXWrapper. As usual when referencing a library project, I also 
right-clicked the References section in EnumerateFonts, selected Add Reference, and in the Add 
Reference dialog box selected Projects at the left and DirectXWrapper. 

The XAML file in EnumerateFonts contains a List Box.. 

Project: EnumerateFonts | File: MainPage.xaml (excerpt) 

<Grid Background=" {StaticResource ApplicationPageBackgroundThemeBrush}"> 

<ListBox Name="l stbox"> 

<ListBox.ItemTemplate> 

<DataTemplate> 

<TextBlock Text="{Binding}" 

FontFami ly="{Binding}" 

FontSize="24" /> 

</DataTemplate> 

</ListBox.ItemTemplate> 

</ListBox> 

</Grid> 


The ItemTemplote obviously anticipates that the ListBoxmW be filled with font family names. Each 
name is displayed with a font based on that family. That ListBox is filled from the constructor of the 
code-behind file: 

Project: EnumerateFonts I File: MainPage.xaml.es 

using Windows.UI.Xaml.Controls; 
using DirectXWrapper; 

namespace EnumerateFonts 

{ 

public sealed partial cl ass MainPage : Page 

{ 

public MainPageO 

{ 

this. InitializeComponent(); 

Wri teFactory wri teFactory = new Wri teFactoryO ; 

WriteFontCol1ection writeFontCol1ection = 

writeFactory.GetSystemFontCol1ection(); 

int count = writeFontCol1ection.GetFontFami1yCount(); 
string [] fonts = new string [count]; 

for (int i =0; i < count; i++) 

{ 

WriteFontFamily writeFontFamily = 

writeFontCol1ection.GetFontFamily(i); 

WriteLocalizedStrings writeLocalizedStrings = 
writeFontFamily.GetFami1yNames(); 

int index; 

if (writeLocalizedStrings.FindLocal eName("en-us" , out index)) 
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fonts[i] = writeLocalizedStrings.GetStri ng(i ndex); 

} 

else 

{ 

fonts[i] = writeLocalizedStrings.GetStri ng(0); 

} 

} 

1stbox.ItemsSource = fonts; 


As you can see, the classes and methods in DirectXWrapper are accessed and used as if they were 
normal Windows Runtime classes. The program attempts to find a font with the locale named "en-us"; 
if that's not available, it just gets the first one in the collection. In reality, many Windows 8 fonts have 
only one name, but some designed for languages of the Far East have alternative names in Chinese, 
Korean, or Japanese. 

Here’s the beginning of a list such as you might see on your own system: 


SimSun-ExtB 

KodchiangUPC 

Kokila 

Shonar Bangla 

Mangal 

BrowalliaUPC 
Sakkal Majalla 

UlyUPC 

Palatino Linotype 

MoolBoran 

Franklin Gothic 

Cordia New 

Arial 

AngsanaUPC 


Configurations and Platforms 

The Visual Studio standard toolbar includes two drop-down combo boxes identified by the tooltips 
"Solution Configurations" and "Solution Platforms.” 

The Solution Configurations box has three options: 

■ Debug 


Release 
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■ Configuration Manager... 

The first two items allow you to compile your program in two different ways, Normally, you'll want 
to use the Debug configuration during program development. But when most of the debugging has 
been completed, you’ll want to switch over to the Release configuration for better code optimization 
and performance. 

In all the projects in this book prior to EnumerateFonts, the Solution Platforms box displays five 
options: 

■ Any CPU 

■ ARM 

■ x64 

■ x86 

■ Configuration Manager... 

In all the projects in this book prior to EnumerateFonts, that Solution Platforms box has probably 
displayed the default for C# projects, which is Any CPU. 

This is as it should be. When you compile a C# program in Visual Studio, your source code is 
compiled into Intermediate Language, or IL. When the program runs, this IL is compiled into native 
code appropriate for the processor on which the program is running. This is one of the big advan¬ 
tages of using a managed language like C#: The distributable executable consists of Intermediate 
Language that is independent of the processor that later runs the program. This is true even if your 
program uses P/Invoke to access Win32 functions. 

With a C# project, you have the ability to use the Solution Platforms combo box to change the 
platform to ARM, x64, or x86. The compiler still generates Intermediate Language but the executable 
will run only on specific processors. If you specify ARM, the program will run on machines with ARM 
processors only. If you specify x64, the program will run on 64-bit Intel processors only. If you specify 
x86, the program will run on both 32-bit and 64-bit Intel processors. 

In general, unless you have a reason for doing so, you do not want to restrict your C# program to 
specific processors. You want the Solution Platforms box to read Any CPU. (If you want your program 
to do something a little different on Intel and ARM processors, you can use the G etNativeSystemlnfo 
function described earlier in this chapter.) 

However, once you begin introducing C++ code into your application, everything changes. Visual 
Studio does not compile C++ code to Intermediate Language; it’s compiled to native machine code 
for a specific processor. That executable will run only on a processor of that sort — with the exception 
that code compiled for a 32-bit Intel processor will also run on 64-bit Intel processors. 

Moreover, if you have a multiproject application that consists of some C# code and some C++ 
code (such as the EnumerateFonts solution), the platforms of the multiple projects must be the same 
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and they must match the platform on which you’re running the application. It might seem reasonable 
that an "Any CPU" C# project can reference an 〃 x64 〃 C++ project, but that is not the case. 

To see the platforms of the individual projects, you can invoke the Configuration Manager dialog 
box by selecting Configuration Manager from either combo box. For the C# projects in the solution, 
the platform options are 

■ Any CPU 

■ ARM 

■ x64 

■ x86 

For C++ projects, the platform options are 

■ ARM 

■ Win32 

■ x64 

The C++ Win32 platform option is equivalent to the C# x86 platform. 

The only possible combinations of platform options that work are these: 

■ C# ARM and C++ ARM running on an ARM processor 

■ C# x64 and C++ x64 running on an Intel 64-bit processor 

■ C# x86 and C++ Win32 running on an Intel 32-bit or 64-bit processor 

If you select ARM, x64, x86, or Win32 from the Solution Platforms combo box, you’ll get one of these 
three combinations. 

In any program in this book, try selecting ARM from the Solution Platforms combo box and then 
pressing F5. The program will build just fine but it won’t deploy because you're not running Visual 
Studio on an ARM-based machine. I know this for a fact because Visual Studio does not run on ARM 
processors. 

If you have an ARM-based machine running Windows 8 — such as the initial release of the 
Microsoft Surface machines — you probably want to test your programs on it. However, you can’t run 
Visual Studio on the Surface, so you have to get the application on that machine in another way. 

For debugging and testing purposes, the easy way is remote deployment, which works over a WiFi 
network and is described in a blog entry by Tim Heuer: http://timheuer.com/blog/archive/2012/10/26/ 
remote-debugging-windows-store-opps-on-surfoce-orm-devices.ospx. Once you have everything set 
up and your Surface is running the Remote Debugger and it’s not asleep or displaying the lock screen, 
make the following two selections: 

■ Select the platform of the remote machine from the Solution Platforms combo box. 
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■ Select Remote Machine from the drop-down to the left of the Solution Configurations 
combo box. 

It’s helpful to make these two selections in this order because the target machine is associated with 
the platform. If you select Remote Machine first and then the platform, Visual Studio will switch back 
to Local Machine. 

If your solution consists solely of C# code, the Solution Platforms combo box should be Any CPU 
regardless what machine you’re deploying to. If your solution has some C++ code and you’re deploy¬ 
ing to an ARM-based machine such as Microsoft Surface, select ARM from the Solution Platforms 
combo box. 

For distribution purposes — whether you’re uploading an application to the Windows Store or 
you're putting together a program for deployment to other machines — another approach is involved. 
This requires creating application packages in Visual Studio by selecting Create App Packages from 
the Store menu. 

During this process, you’ll encounter a dialog box with the heading "Select and Configure 
Packages” with a table of architectures. If your project has only C# code, you can select an 
architecture of "Neutral," which is equivalent to Any CPU. However, if your project has C++ code, 
you can't select that. You must select one or more of the other options: x64, x86, and ARM. You’ll 
probably want to select all three for deployment on any type of machine. 

If you're not uploading a package to the Windows Store but want to install it on another machine, 
Visual Studio creates directories for the various architectures that you’ve selected. Each of these 
directories contains a Windows PowerShell script — a file with the extension psl — that you can run to 
deploy the application. One approach is to copy the directory to a USB thumb drive (or have Visual 
Studio create it there), bring the thumb drive to the other machine (such as a Microsoft Surface), and 
run the script to install the application on that machine. 

Interpreting Font Metrics 

Font metrics is the term that refers to the sizes of characters and character strings in a particular 
font. For most cases, you don’t need font metric information when working with text in a Windows 8 
program. The Text Block element determines a size for the particular text and font it’s being asked to 
display, and usually that’s adequate. However, if you're going to be doing sophisticated text layout, 
font metrics are a necessity, and occasionally they are required for some unusual tasks. 

I’m going to restrict this discussion to vertical measurements — heights rather than widths. These 
vertical measurements vary by font, font style (italics), font weight (bold), and font size, but they are 
independent of any particular character or string. 

The LookAtFontMetrics program provides a visual demonstration of the correlation between 
the size of a text string as calculated by the TextBlock element and the font metrics provided by 
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DirectWrite. The project has the same references to the DirectXWrapper project as EnumerateFonts. 
The XAML file has a similar List Box but also includes a TextBlock in a Border with some semidefined 
Line elements: 


Project: LookAtFontMetrics I File: MainPage.xaml (excerpt) 

<Grid Background:” {StaticResource ApplicationPageBackgroundThemeBrush}"> 
<Grid.ColumnDefinitions> 

<ColumnDefinition Wi dth="Auto" /> 

<ColumnDefinition Width="*" /> 

</Grid.ColumnDefinitions> 

<ListBox Name="l stbox" 

Grid.Col umn="0" 

Width= ,, 300" 

Selecti onChanged="OnLi stBoxSelectionChanged"> 

<ListBox.ItemTempl ate> 

<DataTemplate> 

〈TextBlock Text="{Bi nding}" 

FontFami1 y="{Binding}" 

FontSize="24" /> 

</DataTemplate> 

</ListBox.ItemTemplate> 

</ListBox> 


〈Grid Grid.Col umn="l" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Center"> 

〈Border BorderBrush="{Stati cResource ApplicationForegroundThemeBrush}" 
BorderThickness="l"> 

<Grid> 

<Grid.Resources 〉 

<Style TargetType="Li ne"> 

〈Setter Property=" Stroke" Value="Red" /> 

〈Setter Property="StrokeThi ckness" Val ue="2" /> 
〈Setter Property="Xl" Value:"。" /> 

</Style> 

</Grid.Resources 〉 


〈TextBlock Name="txtbl k" 

Text="Texti ng" 

FontSize="192" 

Si zeChanged="OnTextBl ockSizeChanged" /> 


<Line x : Name="ascenderLi ne" Y1="0" Y2="0" /> 
<Line x:Name="capsHei ghtLine" /> 

<Line x : Name="xHei ghtLine" /> 

〈Line x : Name="basel ineLine" Stroke="Bl ue" /> 
<Line x:Name="descenderLi ne" /> 

<Line x : Name="l ineGapLine" /> 

</Gri d> 

</Border> 

</Gri d> 


</Grid> 
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The constructor of this program is pretty much the same as the previous program in that it fills 
up the ListBox with the available fonts. The program also handles a SelectionChanged event from the 
ListBox by setting the FontFamily property of the TextBlock and obtaining a WriteFontMetries value 
from DirectXWrapper. The program then uses these font metrics to set the Y1 and Y2 properties of 
the various Line elements: 

Project: LookAtFontMetrics I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

WriteFactory writeFactory; 

WriteFontCol1ection writeFontCol1ection; 

public MainPageO 

{ 

this .InitializeComponent(); 

writeFactory = new WriteFactory (); 

writeFontCol1ection = writeFactory.GetSystemFontCol1ection(); 
int count = writeFontCol1ection.GetFontFami1yCount(); 
stri ng[] fonts = new string [count]; 

for (int i =0; i < count; i++) 

{ 

WriteFontFamily writeFontFamily = writeFontCol1ection.GetFontFami1y(i); 

WriteLocalizedStrings writeLocalizedStrings = writeFontFami1y.GetFami1yNames(); 
int nameCount = wri teLocal i zedStri ngs .GetCountO ; 
int index; 

if (writeLocalizedStrings.FindLocal eName("en-us" , out index)) 

{ 

fonts[i] = writeLocalizedStrings.GetString(i ndex); 

} 

} 

1stbox.ItemsSou rce = fonts; 

Loaded += (sender, args)=> 

{ 

lstbox.Selectedlndex = 0; 

}； 

} 

void OnListBoxSelectionChanged (object sender, SelectionChangedEventArgs args) 

{ 

string fontFamily = (sender as ListBox) .Selectedltem as string; 

if (fontFamily == null) 
return ; 

txtblk.FontFami1y = new FontFami1y (fontFami1y); 
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int index; 

if (writeFontCol1ection.FindFami1yName(fontFami1y, out index)) 

{ 

Wri teFontFami 1 y writeFontFamily = writeFontCol1ection.GetFontFami1y(index); 

WriteFont writeFont = writeFontFami1y.GetFirstMatchingFont (FontWeights .Normal, 

FontStretch. Normal, 
FontStyle. Normal); 

WriteFontMetrics fontMetrics = writeFont.GetMetrics(); 
double fontSize = txtblk.FontSize; 

double ascent = fontSize * fontMetri cs .Ascent / fontMetri cs.Designllni tsPerEm; 
double capsHei ght = fontSize * fontMetri cs .CapHei ght / fontMetri cs. Desi gnllni tsPerEm; 
double xHei ght = fontSize * fontMetri cs .XHei ght / fontMetri cs. Desi gnllni tsPerEm; 

double descent = fontSize * fontMetri cs. Descent / fontMetri cs. Desi gnllni tsPerEm; 

double lineGap = fontSize * fontMetri cs. Li neGap / fontMetri cs. Desi gnllni tsPerEm; 

baselineLine.Y1 = baselineLine.Y2 = ascent; 
capsHeightLine.Y1 = capsHeightLine.Y2 = ascent - capsHeight; 
xHeightLine.Y1 = xHeightLine.Y2 = ascent - xHeight; 
descenderLine.Y1 = descenderLine.Y2 = ascent + descent; 

1ineGapLine.Y1 = 1ineGapLine.Y2 = ascent + descent + lineGap; 



void OnTextBlockSizeChanged (object sender, SizeChangedEventArgs args) 
{ 

double width = txtblk.ActualWidth; 
ascenderLine.X2 = width; 
capsHeightLine.X2 = width; 
xHeightLine.X2 = width; 
baselineLine.X2 = width; 
descenderLine.X2 = width; 

1ineGapLine.X2 = width; 

} 


The DWRITE_FONT_METRICS in DirectWrite has a field named designUnitsPerEm that for most 
fonts is a nice round number such as 256,1024, 2048, or 4096 and only occasionally a peculiar value 
like 1000. As the name implies, this is the height of the grid the typographer used to define the char¬ 
acters of the font. All the other heights in the structure are relative to this design height. This is how 
all the fields of the structure can be integers. To obtain pixel height values for a particular font and 
font size, the fields of this structure must be multiplied by FontSize and divided by designilnitsPerEm. 

This is what the LookAtFontMetrics program does in setting the Y1 and Y2 properties of all the 
Line elements. For some fonts, the results won’t look quite right because those fonts are designed for 
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non-Latin alphabets. But for the standard fonts used for languages based on Latin alphabets, the lines 
calculated from the font metrics are dead on: 


CordiaUPC 

Khmer UI 

Aharoni 

Microsoft Uighur 


Times New Roman 


Candara 

Ebrima 

DiUemaUPC 

MS Mincho 
MS PMincho 

Browallia New 
Aldhabi 


DFKai-SB 
SimHei 



The line on which the characters sit — the blue line if you’re reading an electronic version of this 
book — is the baseline. In many fonts, rounded characters (such as 'e') dip a tad below that line. The 
next line up from the baseline is the x-height, which is the height of lowercase letters. Again, some 
rounded characters go slightly above that line. Next up is the caps height, which indicates the height 
of capital letters. The ascent line is even higher — at the very top of the rectangle that the TextBlock 
calculates for itself — and accounts for diacritical marks that might appear on some letters, such as the 
umlaut (0). Below the baseline is the area for descenders of those letters that go below the baseline. 
At the very bottom is a line gap, which is zero for many fonts. Here’s a diagram using the names 
defined in the original DWRITE_FONT_METRICS structure: 



The height that TextBlock calculates for itself is based on the sum of the ascent, descent, and lineGap 
fields. 
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In Chapter 10, I showed a program that displayed a tilted shadow of a text string: 



At the time I indicated that it's not possible to do something similar for an arbitrary font where the 
shadow tilts back from baseline. You need to know the font metrics, and now that we have those, let’s 
try it. 

Here's the XAML file for BaselineTiltedShadow. There's another List Box for the system fonts, and 
there’s some XAML for text and a shadow: 


Project: BaselineTiltedShadow I File: MainPage.xaml (excerpt) 

<Grid Background:” {StaticResource ApplicationPageBackgroundThemeBrush}"> 
<Grid.ColumnDefinitions> 

<ColumnDefinition Wi dth="Auto" /> 

<ColumnDefinition Width="*" /> 

</Grid.ColumnDefiniti ons> 


<ListBox Name="l stbox" 

Grid.Col umn="0" 

Width="300" 

Selecti onChanged="OnLi stBoxSelectionChanged"> 
<ListBox.ItemTempl ate> 

<DataTemplate> 

〈TextBlock Text="{Bi nding}" 

FontFami ly="{Binding}" 

FontSi ze="24" /> 

</DataTemp1ate> 

</ListBox.ItemTempl ate> 

</ListBox> 


〈Grid Grid.Col umn="l" 

HorizontalAli gnment="Center" 
VerticalAli gnment="Center"> 
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〈TextBlock Name="shadowTextBl ock" 

Text="shadow" 

FontSize="192" 

Foreground="Gray"> 

<TextBlock.RenderTransform> 

<CompositeTransform ScaleY="l. 5" SkewX="-60" /> 
</TextBlock.RenderTransform> 

</TextBlock> 


<TextBlock Name="foregroundText Block" 
Text="shadow" 


</Grid> 
</Crid> 


FontSize="192" /> 


Those two TextBlock elements are missing FontFomily properties, which are set from the 
code-behind file to the font selected in the ListBox. The TextBlock for the shadow is also missing a 
RenderTransformOrigin property. The constructor of the code-behind file that initializes the ListBox is 
the same as in the previous program; the crucial part of the Selection Changed property calculates this 
RenderTransformOrigin for the shadow based on the fractional percentage of the font height above 
the baseline: 

Project: BaselineTiltedShadow I File: MainPage.xaml.es (excerpt) 

void OnListBoxSelectionChanged (object sender, SelectionChangedEventArgs args) 

{ 

string fontFamily = (sender as ListBox). Selectedltem as string; 

if (fontFamily == null) 
return ; 

foregroundTextBlock.FontFamily = new FontFami1y (fontFami1y); 
shadowTextBlock.FontFamily = foregroundTextBlock.FontFamily; 

int index; 

if (writeFontCol1ection.FindFami1yName(fontFami 1y, out index)) 

{ 

WriteFontFami1y writeFontFamily = writeFontCol1ection.GetFontFamily(index); 

WriteFont writeFont = writeFontFami1y.GetFirstMatchingFont (FontWeights. Normal, 

FontStretch. Normal, 

FontStyle. Normal); 

Wri teFontMetri cs fontMetn.es = wri teFont. GetMetricsO ; 

double f ractionAboveBaseline = (double)fontMetri cs.Ascent / 

(fontMetrics.Ascent + fontMetrics.Descent + fontMetrics.LineGap); 

shadowTextBlock.RenderTransformOrigin = new Point (0, fractionAboveBaseline); 

} 

} 
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And here it is: 


(S) ⑨⑤今 oa ⑰⑤々⑩ □ 

I O — > ^71 e > \J ♦•- 


Book Antiqua 


Century Gothic 
Haettensdiweier 

OS Outlook 

Ternpus Sans ITC 
"Prisfina 
f apyrus 

Lucid^HctndMrCZtn^ 

Kristen UC 

Mce ITC 

Sicnck Soiipt 0tceT 
Fre^st^e Script 




Drawing on a SurfacelmageSource 

There is only one other class in DirectXWrapper. I called it SurfocelmogeSourceRenderer, and it takes a 
rather different architectural approach than the classes in the library that wrap the DirectWrite classes. 
The SurfocelmogeSourceRenderer class instantiates a whole bunch of DirectX objects and uses those 
to provide a high-level interface to drawing lines on an object of type SurfacelmageSource. 

SurfacelmageSource derives from ImogeSource and hence can be set to the Source property of 
Image or to the ImageSource property of ImogeBrush. It is basically a bitmap. However, you can use 
DirectX to draw graphics (or text) on this bitmap. The SurfocelmogeSourceRenderer class performs all 
the necessary overhead and exposes three public methods: Clear, Draw Line, and Update. Obviously, it 
could be expanded to include a lot more. 

Here’s the header file: 

Project: DirectXWrapper I File: SurfacelmageSourceRenderer.h 

#pragma once 

namespace DirectXWrapper 

{ 

public ref class SurfacelmageSourceRenderer sealed 

{ 

private : 

int width, height; 

Microsoft: : WRL :: ComPtr<ID2DlFactory> pFactory; 

Microsoft: : WRL : : ComPtr<ID3DHDevice> pd3dDevice; 

Microsoft : : WRL : : ComPtr<ID3DHDeviceContext> pd3dContext; 

Microsoft :: WRL :: ComPtr<ISurfaceImageSourceNative> sisNative; 
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Microsoft: : WRL :: ComPtrcIDXGIDevi ce> pDxgiDevice; 

Microsoft: : WRL :: ComPtr<ID2DlBitmapRenderTarget> bitmapRenderTarget; 

Microsoft: : WRL :: ComPtr<ID2DlBitmap> bitmap; 

Microsoft: : WRL :: ComPtr<ID2DlSolidColorBrush> solidColorBrush; 

Microsoft: : WRL :: ComPtr<ID2DlStrokeStyl e> strokeStyle; 
bool needsUpdate; 

public: 

SurfaceImageSourceRenderer( 

Windows::UI: : Xaml :: Media: : Imaging :: SurfacelmageSourceA surfacelmageSource, 
int width, int height); 
void Clear(Windows::UI: : Col or color); 

void DrawLine(Windows::Foundation:: Point ptl, Windows::Foundation:: Point pt2, 

Windows::UI: : Col or color, double thickness); 

void UpdateO; 
private: 

ID2DlRenderTarget * CreateRenderTarget(Microsoft :: WRL: : ComPtr<IDXGISurface> pSurface); 
D2D1: : ColorF ConvertColor(Windows::UI: : Color color); 

}； 

} 


The public constructor requires an instance of the SurfacelmageSource class. This is allowed in a 
public constructor because it's a Windows Runtime type defined in the Windows.Ul.Xoml.Medio 
.Imaging namespace. This constructor contains code that really can’t be written from scratch by 
anyone who’s not a DirectX wizard. I am certainly not, so I lifted much of this code from other sample 
projects intended to illustrate how to use SurfacelmageSource: 

Project: DirectXWrapper I File: SurfacelmageSourceRenderer.cpp (excerpt) 

SurfacelmageSourceRenderer: : SurfacelmageSourceRenderer (SurfacelmageSourceA SurfacelmageSource, 

int width, int height) 

{ 

// Save the image width and height 
thi s->width = width; 
this->height = height; 

// Create Factory 

D2D1_FACT0RY_0PTI0NS options = { D2D1_DEBUG_LEVEL_N0NE }; 

HRESULT hr = D2DlCreateFactory(D2Dl_FACTORY_TYPE_SINGLE_THREADED, 

— uuidof (ID2DlFactory) , 

•^options, 

&pFactory); 

if OSUCCEEDED(hr)) 

throw ref new COMException(hr) ; 

// Create ISurfacelmageSourceNative object 
Ilnspectable* sislnspectable = (Ilnspectabl e*) 

rei nterpret_cast<IInspectabl e*>(surfaceImageSource); 
sisInspectable->QueryInterface( — uuidof (ISurfacelmageSourceNati ve) , (voi d sNative); 

// Create Device and Device Context 
D3D_FEATURE_LEVEL featureLevels[]= 

{ 

D3D_FEATURE_LEVEL_11_1, 
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D3D_FEATURE_LEVEL_11_0 ， 
D3D_FEATURE_LEVEL_10_1 ， 
D3D_FEATURE_LEVEL_10_0 ， 
D3D_FEATURE_LEVEL_9_3 ， 
D3D_FEATURE_LEVEL_9_2, 
D3D_FEATURE_LEVEL_9_1 ， 


hr = D3DllCreateDevi ce(nul 1ptr , 

D3D_DRIVER_TYPE_HARDWARE, 

0 , 

D3D11_CREATE_DEVICE_SINGLETHREADED | 

D3D11_CREATE_DEVICE_BGRA_SUPP0RT, 
featureLevels, 

ARRAYSIZE(featureLevels), 
D3D11_SDK_VERSI0N, 

&pd3dDevice, 
nullptr, 

&pd3dContext); 


if OSUCCEEDED(hr)) 

throw ref new COMExcepti on(hr); 


// Get DXGIDevice 

hr = pd3dDevice.As(&pDxgiDevice); 


if (!SUCCEEDED(hr)) 

throw ref new COMException (hr); 


sisNative->SetDevice(pDxgiDevi ce.Get()); 

// Begin drawing 

RECT update = { 0, 0, width, height }; 

POINT offset; 

IDXGISurface * dxgiSurface; 

hr = sisNative->BeginDraw(update, &dxgiSurface, &offset); 


if (!SUCCEEDED(hr)) 

throw ref new COMException (hr); 

ID2DlRenderTarget * pRenderTarget = CreateRenderTarget(dxgiSurface); 

// But only go far enough to create compatible BitmapRenderTarget 
// and get the Bitmap for updating the surface 

pRenderTarget->CreateCompatibleRenderTarget(&bitmapRenderTarget); 
bitmapRenderTarget->GetBitmap(&bitmap); 

// End drawing 
sisNative->EndDraw(); 
pRenderTarget->Rel ease(); 
dxgiSurface->Release(); 

// Create a SolidColorBrush for drawing "lines 

bitmapRenderTarget->CreateSolidColorBrush(D2Dl: : ColorF(0, 0, 0, 0 )， &solidColorBrush); 

// Create StrokeStyle for drawing lines 
D2D1_STR0KE_STYLE_PR0PERTIES strokeStyleProperties = 
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D2D1_CAP_STYLE_R0UND, 
D2D1_CAP_STYLE_R0UND, 
D2D1_CAP_STYLE_R0UND, 
D2D1_LINE_]0IN_R0UND, 
10 , 

D2D1_DASH_STYLE_S0LID, 
0 


hr = pFactory->CreateStrokeStyleC&strokeStyleProperties, nul1ptr , 0 ， &strokeStyle); 


} 


if (!SUCCEEDED(hr)) 

throw ref new COMException(hr) ; 


This constructor makes use of a private method that also comes into play during drawing 
operations. This method creates an object of type ID2DlRenderTorget on which the actual drawing 
takes place: 


Project: DirectXWrapper I File: SurfacelmageSourceRenderer.cpp (excerpt) 

ID2DlRenderTarget* SurfacelmageSourceRenderer: : CreateRenderTarget(ComPtr<IDXGISurface> pSurface) 

{ 

D2D1_PIXEL_F0RMAT format = 

{ 

DXGI_FORMAT_UNKNOWN, 

D2D1_ALPHA_M0DE_PREMULTIPLIED 

}； 

float dpiX, dpiY; 

pFactory->GetDesktopDpi (&dpiX, «&dpi Y); 

D2D1_RENDER_TARGET_PR0PERTIES properties = 

{ 

D2D1_RENDER_TARGET_TYPE—DEFAULT, 

format, 

dpiX, 

dpiY, 

D2D1_RENDER_TARGET_USAGE_N0NE, 

D2D1_FEATURE_LEVEL_DEFAULT 

}； 

ID2DlRenderTarget * pRenderTarget; 

HRESULT hr = pFactory->CreateDxgiSurfaceRenderTarget(pSurface.Get(), 

&properties, &pRenderTarget); 

if (!SUCCEEDED(hr)) 

throw ref new COMException(hr); 

return pRenderTarget; 

} 
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Notice that in the constructor and this method I’ve defined two pointers to DirectX objects (named 
dxgiSurface and pRenderTarget) for which I did not use the ComPtr wrapper. This is because I was 
using these objects only for a very short period of time and released them "manually” with calls to the 
Release method. 

The Clear method essentially calls the Clear method of the ID2DlBitmopRenderTarget object saved 
as a field: 


Project: DirectXWrapper I File: SurfacelmageSourceRenderer.cpp (excerpt) 

void SurfacelmageSourceRenderer : : Cl ear (Col or color) 

{ 

bitmapRenderTarget->BeginDraw(); 
bitmapRenderTarget->Clear(ConvertColor(color)); 
bitmapRenderTarget->EndDraw(); 
needsUpdate = true; 

} 

Because this is a public method, the argument must be a Windows Runtime type, and so it is. 
However, the Color structure defined in the Windows Runtime is the not the same as the various color 
structures in DirectX, which means that the color must be converted in this private method: 


Project: DirectXWrapper I File: SurfacelmageSourceRenderer.cpp (excerpt) 

D2D1: : ColorF SurfacelmageSourceRenderer: : Converted or (Col or color) 

{ 

D2D1: : ColorF colorf(color.R / 255.Of, 

color.G / 255.Of, 
color.B / 255.Of, 
color.A / 255.Of); 

return colorf; 

} 


Points must be converted as well. The public Draw Line method that I’ve defined renders a line 
between two points, but the method begins by converting those Windows Runtime Point values to 
DirectX D2D1_P0INT_2F values for passing to the Draw Line method of the ID2DlBitmapRenderTorget 
object: 


Project: DirectXWrapper I File: SurfacelmageSourceRenderer.cpp (excerpt) 

void SurfacelmageSourceRenderer :: DrawLine(Poi nt pointl, Point point2, 

Color color, double thickness) 

{ 

// Convert the points 

D2D1_P0INT_2F ptl = { (float) pointl.X, (float)pointl. Y }; 
D2D1_P0INT_2F pt2 = { (float) point2.X, (float)poi nt2.Y }; 

// Convert the color for the SolidColorBrush 
solidColorBrush->SetColor(ConvertColor(color)); 
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// Draw the line 
bitmapRenderTarget->BeginDraw(); 

bitmapRenderTarget->DrawLine(ptl, pt2, solidColorBrush.Get(), 

(float)thi ckness, 
strokeStyle.Get()); 

bitmapRenderTarget->EndDraw(); 
needsUpdate = true ; 


Obviously, the ID2DlBitmopRenderTorget interface defines many other methods besides Draw Line, 
but if you're going to make extensive use of these other methods in your application, it might start 
making more sense to move at least some of the application into C++. 

Both Clear and DrowLine draw on an ID2D1 BitmapRenderTarget, and the SurfacelmageSource 
object must be updated from that. This occurs in the Update method: 


Project: DirectXWrapper I File: SurfacelmageSourceRenderer.cpp (excerpt) 

void SurfacelmageSourceRenderer : : UpdateO 

{ 

// Check if needs update 
if (!needsUpdate) 
return ; 

needsUpdate = false; 

// Begin drawing 

RECT update = { 0, 0, width, height }; 

POINT offset; 

IDXGISurface * dxgiSurface; 

HRESULT hr = sisNative->BeginDraw(update, &dxgiSurface, &offset); 

if (!SUCCEEDED(hr)) 

throw ref new COMException(hr) ; 

ID2DlRenderTarget * renderTarget = CreateRenderTarget(dxgiSurface); 
renderTarget->BeginDraw(); 

// Draw the bitmap to the surface 

D2D1_RECT_F rect = { 0, 0, (float)wi dth, (fl oat) height }; 
renderTarget->DrawBitmapCbitmap.Get(), &rect); 

// End drawing 
renderTarget->EndDraw(); 
sisNative->EndDraw(); 

// Release update resources 
renderTarget->Release(); 
dxgiSurface->Release(); 


That concludes the SurfacelmageSourceRenderer source code. The class is demoed in the SpinPaint 
project. This program displays a spinning disk on which you can draw simply by holding your finger 
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still on the screen or by moving it around. But what gets drawn is also drawn three additional times as 
mirror images, creating an interesting pattern with a minimum of effort: 



I wrote the first version of SpinPaint for the coffee-table-sized computers now known as Microsoft 
PixelSense. I then ported the program to Silverlight using WriteableBitmop and Windows Phone 7 
using XNA. 

In the Windows 8 version of SpinPaint, the XAML file defines a Grid called referencePonel that sits 
in the center of the page. During the Loaded event this Grid is given square dimensions the same size 
as the SurfocelmageSource that it also creates. Within this Grid is another Grid named rotating Panel 
that (as the name implies) rotates. This inner Grid consists of some background shading simply to 
make it obvious that something is spinning prior to anything being drawn on it. On top of that is an 
Image element for displaying the SurfocelmageSource bitmap and a clipping circle: 

Project: SpinPaint | File: MainPage.xaml (excerpt) 

<Grid Background="{StaticResource ApplicationPageBackgroundThemeBrush}"> 

<Grid Name="referencePanel " 

Margin="24" 

HorizontalA1i gnment="Center" 

VerticalAli gnment="Center"> 

<Grid Name=" rotatingPanel"> 

<Grid.RenderTransform> 

<RotateTransform x: Name=" rotate" /> 

</Grid.RenderTransform> 

<E11ipse> 

〈 Ellipse.Fill > 

<LinearGradientBrush> 

<GradientStop 0ffset="0" Color="Black" /> 

<GradientStop Offset="l" Color="Whi te" /> 

</LinearGradientBrush> 
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</El1ipse.Fill 〉 
</El1ipse> 


<Image Name="image" 

Stretch="None" /> 

<!-- Cover all but a circle (poor man's clipping)--> 

<Path Fi1 l="{Stati〔Resource ApplicationPageBackgroundThemeBrush}" 
Stretch="Uni form"> 

<Path.Data> 

<GeometryGroup> 

<RectangleGeometry Rect="0 0 100 100" /> 

<E11ipseGeometry Center="50 50" Radi usX="50" Radi usY="50" /> 
</GeometryGroup> 

〈 /Path.Data 〉 

</Path> 

</Gri d> 

</Gri d> 


<TextBlock x : Name="pageTi tle" 
Text="Spi n Paint” 
FontSize="48" 
Margin="24"> 
<TextB"lock. Foreground 〉 
<SolidColorBrush /> 
</TextBlock.Foreground 〉 
</TextBlock> 


<Button Content="clear" 

HorizontalA1i gnment="Ri ght" 
VerticalAli gnment="Bottom" 
FontSize="48" 

Margin="24" 

Cli ck="0nCl earButtonClick" /> 

</Grid> 


The Loaded handler determines a good size for the SurfocelmogeSource object based 
on the dimensions of the screen and the view state. The Loaded handler also creates a 
SurfocelmogeSourceRenderer from the DirectXWrapper library: 

Project: SpinPaint | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 


int dimension; 

SurfacelmageSourceRenderer surfacelmageSourceRenderer; 
RotateTransform inverseRotate = new RotateTransformO ; 

public MainPage() 

{ 

InitializeComponentC); 

Loaded + =0nMainPageLoaded; 

} 
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void OnMai nPageLoaded(object sender, RoutedEventArgs args) 

{ 

// Find the dimension of the square bitmap 

if (ApplicationView.Val ue == ApplicationViewState. Ful1ScreenPortrait) 

{ 

dimension = (i nt)(thi s .ActualWidth - referencePanel.Margin.Left 

- referencePanel.Margin.Right); 

} 

else 


{ 

} 


dimension = (int)(this .ActualHeight - 


referencePanel.Margin.Top 
referencePanel.Margin.Bottom); 


// Set this size to the reference panel so it doesn't get distorted in Snapped view 
referencePanel.Width = dimension; 
referencePanel.Height = dimension; 


// Create the SurfacelmageSource and renderer 

SurfacelmageSource SurfacelmageSource = new SurfacelmageSourceCdimension , dimension); 
SurfacelmageSourceRenderer = new SurfacelmageSourceRenderer (SurfacelmageSource, 

dimension, dimension); 


image.Source = SurfacelmageSource; 


// Set rotation centers 
rotate.CenterX = dimension / 2; 
rotate.CenterY = dimension / 2; 


inverseRotate.CenterX = dimension / 2; 
inverseRotate.CenterY = dimension / 2; 


// Start the event 

CompositionTarget. Rendering += OnCompositionTargetRendering; 


void OnClearButtonCli ck(object sender, RoutedEventArgs e) 

{ 

SurfacelmageSource SurfacelmageSource = new SurfacelmageSourceCdimension ， dimension); 
SurfacelmageSourceRenderer = new SurfacelmageSourceRenderer (SurfacelmageSource, 

dimension, dimension); 


image.Source = SurfacelmageSource; 

} 


The Clear button simply creates a new SurfacelmageSource and SurfacelmogeSourceRenderer of that 
predetermined size. 

Similar to the FingerPaint series of programs, you can draw on SpinPaint using multiple fingers. 
However, conceptually you’re painting on a spinning disk, and you can simply hold your finger still on 
the screen and paint. In other words, your finger can paint without moving and without generating 
any PointerMoved events! 
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This requires a somewhat different approach to handling Pointer events. A dictionary is 
maintained, of course, and the Fingerlnfo values it contains have Lost Position and ThisPosition fields. 
However, in the On Poin ter Pressed override, LastPosition is initialized to infinite coordinates, and in 
both OnPointerPressed and OnPointerMoved, the ThisPosition field is set to the current finger position. 
Aside from the initialization of the LastPosition field, these overrides never set that field to anything 
else: 

Project: SpinPaint | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

class Fingerlnfo 

{ 

public Point LastPosition; 
public Point ThisPosition; 

} 

Dictionary<uint, FingerInfo> fingerTouches = new Dictionary<uint, Fi ngerInfo>() ; 


protected override void OnPointerPressed(Poi nterRoutedEventArgs args) 

{ 

uint id = args.Pointer.Pointerld; 

Point pt = args.GetCurrentPoint(referencePanel).Position; 

if (fingerTouches.ContainsKeyCid)) 
fingerTouches.Remove(i d); 

Fingerlnfo fingerlnfo = new Fingerlnfo 

{ 

LastPosition = new Point(Double .Positivelnfinity, Double .Positivelnfinity), 
ThisPosition = pt 

}； 

fingerTouches.Add(id, fingerlnfo); 

CapturePointer(args■Pointer); 
base. OnPointerPressed(args); 

} 


protected override void OnPointerMoved(Poi nterRoutedEventArgs args) 

{ 

uint id = args.Pointer.Pointerld; 

Point pt = args.GetCurrentPoint(referencePanel).Posi tion; 

if (fingerTouches.ContainsKeyCid)) 

fingerTouches[id].ThisPosition = pt; 

base. OnPointerMoved(args); 

} 


protected override void OnPointerReleased(Poi nterRoutedEventArgs args) 

{ 

uint id = args.Pointer.Poi nterld; 
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if (finge 「 Touches■ContainsKeyCid)) 
fingerTouches.Remove(i d); 


base.OnPoi nterReleased(args); 

} 

protected override void OnPointerCaptureLost(Poi nterRoutedEventArgs args) 

{ 

uint id = args.Pointer.Pointerld; 

if (fingerTouches.ContainsKeyCid)) 
fingerTouches.Remove(i d); 

base.OnPoi nterCaptureLost(args); 

} 


All the really interesting activity occurs in the CompositionTorget.Rendering event handler. Based 
on the current elapsed time of the application, a rotation angle is calculated to spin the Grid named 
rotatingPanel and to calculate a painting color. This color is also applied to the TextBlock displaying 
the name of the application at the upper-left corner of the page: 


Project: SpinPaint I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

void OnCompositionTargetRendering (object sender, object args) 

{ 

// Get elapsed seconds si nee app began 

TimeSpan timeSpan = (args as RenderingEventArgs) .RenderingTime; 
double seconds = timeSpan.TotalSeconds; 


// Calculate rotation angle 

rotate.Angle = (360 * seconds / 5) % 360; 


// Calculate color and brush 

Color clr; 

double fraction = 6 * (seconds % 10)/10; 


if (fraction < 1) 

clr = Color. FromArgb(255, 255, (byte) (fraction * 255 )， 0); 
else if (fraction < 2) 

clr = Color. FromArgb(255, (byte) (255 - (fraction - 1) * 255), 255, 0); 
else if (fraction < 3) 

clr = Color. FromArgb(255, 0, 255, (byte) ((fraction - 2) * 255)); 
else if (fraction < 4) 

clr = Color. FromArgb(255, 0, (byte) (255 - (fraction - 3) * 255), 255); 
else if (fraction < 5) 

clr = Col or .FromArgb(255 , (byte) ((fraction - 4) * 255), 0, 255); 

else 

clr = Color. FromArgb(255, 255, 0, (byte) (255 - (fraction - 5) * 255)); 


CpageTitle.Foreground as SolidColorBrush) .Color = cl r; 
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// All done if nobody's touching 
if (fingerTouches.Count == 0) 
return ; 


} 

Then, for each finger currently touching the screen, the ThisPosition field of Finger Info is rotated 
so that the point is no longer in screen coordinates but relative to the rotated Image element. It is 
this point along with the Lost Posit ion field of Finger Info that is used for drawing. The four calls to the 
Draw Line method of SurfacelmogeSourceRenderer draw four separate lines in the four quadrants of 
the bitmap: 

Project: SpinPaint | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

void OnCompositionTargetRendering (object sender, object args) 

{ 


bool bitmapNeedsUpdate = false; 


foreach (Fi ngerlnfo fingerlnfo in fingerTouches.Values) 

{ 

// Find point relative to rotated bitmap 
inverseRotate.Angle = -rotate.Angle; 

Point pointl = inverseRotate.TransformPoint(fingerlnfo.ThisPosition); 

if (! Doubl e. IsPositivelnfinity(fingerlnfo.LastPosition.X)) 

{ 

Point point2 = fingerlnfo.LastPosition; 
float thickness = 12; 


// Draw the lines 

surfacelmageSourceRenderer.DrawLine(poi ntl, point2, cl r, thickness); 
surfacelmageSourceRenderer.DrawLi ne(new Point (dimension - pointl.X, pointl.Y )， 

new Point (dimension - point2.X, point2.Y), 
clr, thickness); 


surfacelmageSourceRenderer.DrawLi ne(new Poi nt(pointl.X, dimension - pointl.Y )， 

new Poi nt(point2.X, dimension - point2.Y), 
clr, thickness); 


surfacelmageSourceRenderer.DrawLi ne(new Point (dimension - 

dimension - 
new Point (dimension - 
dimension - 
clr, thickness); 


pointl.X, 
pointl.Y), 
point2.X, 
poi nt2.Y), 


bitmapNeedsUpdate = true; 


fingerlnfo.LastPosition = pointl; 
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// Update bitmap 
if (bitmapNeedsUpdate) 

{ 

surfacelmageSourceRenderer.UpdateO; 


It is also this rotated finger position that is stored back into the Finger Info object as LastPosition. 
This is how a finger sitting on the screen without moving can draw: Even if the finger hasn’t moved 
at all, the current position of that finger was obtained in the OnPointerPressed override and remains 
stored in the ThisPosition field of Finger Info. During every call to CompositionTarget. Rendering, the 
ThisPosition field is rotated with a new angle and a line is drawn from the LastPosition field. The 
rotated position value is then stored back into Fingerlnfo as LastPosition in preparation for the next 
iteration. 

It’s interesting that I first conceived the SpinPaint program for Microsoft PixelSense, where I could 
use a static Contacts class to obtain the current positions of all the fingers touching the screen without 
any touch event handling. Because I could treat finger touches as state rather than events, processing 
those fingers in a CompositionTarget Rendering handler seemed very natural. 

When porting the SpinPaint program to environments with only events for processing touch, I had 
to mimic the touch state of the Contacts class. The ThisPosition field of Fingerlnfo is precisely that: At 
any time, these Fingerlnfo objects in the dictionary indicate the current locations of all the fingers on 
the screen. But I’m not sure I would have even conceived of this program if I hadn’t had experience 
with an environment in which touch was available as a state rather than just events. 

This reinforces my belief that the more you know, the better you’re able to think outside the box. 
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CHAPTER 16 

Rich Text 


T he term "rich text” once meant text displayed with different fonts, sizes, and styling, but now 
that those features are commonplace, rich text has come to refer more vaguely to something 
somewhat beyond the ordinary. The bulk of this chapter focuses on the RichTextBlock element and 
the RichEditBox control, which (as their names suggest) are souped-up versions of TextBlock and 
TextBox. But this chapter also provides a few hints that might help get you started on more extensive 
text-processing jobs. 

The terminology that surrounds fonts has changed somewhat over the years with the switch to 
digital typography. The word typeface traditionally indicated a particular design style of character 
glyphs. Common typefaces are Times New Roman and Helvetica. These typeface designs often have 
variations, most commonly italic and boldface, so a typeface family might include Times New Roman, 
Times New Roman Italic, and Times New Roman Bold. 

A font is a physical implementation of a particular typeface with a particular style and a particular 
size: in predigital typography, for example, 10-point Helvetica Bold. Each character in a particular font 
was a unique chunk of metal type. 

As people began working with text on computers, two trends resulted in the blurring of this 
terminology. First, users preferred thinking of italic or boldface as an attribute rather than an intrinsic 
part of a typeface. For example, rather than changing a particular word from Times New Roman 
to Times New Roman Italic, it was more convenient to apply an Italic attribute to the word regard¬ 
less of the underlying typeface. Second, with the advent of digital outline font technologies such 
as TrueType, the size of font characters became a fairly trivial scaling process, so people no longer 
thought of size as constituting a crucial part of a font specification. 

To help accommodate this different way of thinking, the term font family became common. A font 
family is much like a traditional typeface. It has a name such as Times New Roman or Helvetica. The 
font family is implemented in the Windows Runtime with a FontFomily class and in the TextBlock and 
Control classes with a FontFomily property. A Windows 8 program uses the FontFomily in connection 
with the other font-related properties {FontSize, FontStyle, FontWeight, and Font St retch) for a 
complete font specification. 
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The underlying technology, however, takes a more traditional approach. In Windows, fonts are 
implemented with font files, usually with the extension .TTF ("TrueType font"). These can be found in 
the /Windows/Fonts directory. Many of these files were probably installed along with Windows; some 
of them may have been added to the collection by various applications. Windows Explorer manages 
this directory a little differently from conventional directories, so you don't directly see the filenames. 
(Also in this directory are some bitmap fonts of particular sizes, but these are used for command-line 
windows.) 

What’s listed in the /Windows/Fonts directory instead of filenames are font family names, such as 
Georgia: 


Abg 


Georgia 

Notice that this appears to be several documents. If you double-tap this stack, you'll see another 
screen that displays the individual font files that are members of this font family: 


Abg Abg Abg Abg 

Georgia Bold Georgia Bold Georgia Italic Georgia Regular 

Italic 


If you now right-click one of these and bring up a Properties screen, you’ll see that these are each a 
separate file: in order, georgiab.ttf, georgiaz.ttf, georgiai.ttf, and georgia.ttf. Each file contains scalable 
outlines for many characters — not oil Unicode characters but a substantial subset. 

Some font families contain variations other than Italic and Bold, for example, Oblique or Light or 
Demibold, and some font families contain Compressed or Expanded variations. It is the responsibility 
of Windows to reference a suitable font file when a particular combination of FontStyle, FontWeight, 
and Font St retch properties are specified. 

Some font families do not contain Italic or Bold variations. For those font families, these styles can 
be simulated: by tilting the characters toward the right or making the character strokes a bit wider. 
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Private Fonts 


Your Windows Store program can use any of the outline fonts in the /Windows/Fonts directory, but as 
I discussed in Chapter 15, "Going Native,” DirectWrite is required to actually enumerate the available 
font family names. 


Sometimes programs need to use fonts that might not be installed under Windows. One 
traditional solution is to provide the fonts along with the application and have the user install them, 
but in some cases the program might want the fonts to remain private. Perhaps the fonts have been 
licensed by the font manufacturer strictly for use by the particular application. In this case, the fonts 
should remain private for the application’s exclusive use. 


In such cases, these private font files can be treated as application content and effectively 
embedded in the application executable. The PrivateFonts project demonstrates how this is done. I 
created a folder named Fonts in this project, and then I added eight TrueType files, as shown here: 



Solution 'PrivateFonts' (1 project) 


PrivateFonts 


> A Properties 

> References 


> Assets 

> 篇 Common 
^ 成 Fonts 


[a Kooten.ttf 
a Linds.ttf 
a Miramo.ttf 
» Miramob.ttf 
a Peric.ttf 
a Pericl.ttf 
a Pesca.ttf 
、 Pescab.ttf 

> D App.xaml 

> MainPage.xaml 
Package.appxmanifest 

pi P rivateFo nts_Tem p o ra ryKey. pfx 


Each of these font files has its Build Action set to the default value of Content. 

If you are creating such a program in Visual Studio for other people to run, you cannot simply add 
arbitrary font files to the project. Because these font files will be distributed to a user as part of the 
application, you must have permission to distribute them. For many font files — including many of the 
fonts that come with Windows and Windows applications — distributing the files with your application 
requires that you license the fonts for this purpose from the font manufacturer. 

However, the particular font files I added to my PrivateFonts project have no such restrictions. If 
you're an XNA programmer, you might recognize these font files as the ones that Microsoft licensed 
from the Ascender Corporation for purposes of free distribution with applications. 

A Text Block element in a XAML file can access these fonts with a little different format of the 
FontFamily attribute. Normally, you set FontFomily to a font family name such as "Times New Roman” 


CHAPTER 16 Rich Text 


847 





or "Segoe UL 〃 To use a private font, you must specify a URI indicating the location of the font file, 
followed by a hash (or number) sign, followed by the font family name, as shown here: 


Project: PrivateFonts I File: MainPage.xaml (excerpt) 

<Page ... FontSi ze="36"> 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Grid.ColumnDefinitions> 

<ColumnDefinition Width="*" /> 

<ColumnDefinition Width="*" /> 

<ColumnDefinition Width="*" /> 

<ColumnDefinition Width="*" /> 

</Grid.ColumnDefinitions> 


<StackPanel Grid.Column="0"> 

<TextBlock Text="Kootenay" 

FontFami1 y="ms-appx:///Fonts/Kooten.ttf#Kootenay" /> 

<TextBlock Text="Li ndsey" 

FontFami1 y="ms-appx:///Fonts/Linds.ttf#Lindsey" /> 

〈TextBlock Text="Mi ramonte" 

FontFami1 y="ms-appx:///Fonts/Miramo.ttf#Miramonte" /> 

<TextBlock Text="Mi ramonte Bold" 

FontFami1 y="ms-appx:///Fonts/Miramob.ttf#Mi ramonte" /> 

〈TextBlock Text="Pericles" 

FontFami1 y="ms-appx:///Fonts/Peric.ttf#Pericles" /> 

<TextBlock Text="Peri cles Light" 

FontFami ly="ms-appx: ///Fonts/Pericl.ttf#Pericles" /> 

<TextBlock Text="Pescadero" 

FontFami ly="ms-appx:///Fonts/Pesca.ttf#Pescadero" /> 


<TextBlock Text="Pescadero Bold" 

FontFami1 y="ms-appx:///Fonts/Pescab.ttf#Pescadero" /> 


〈TextBlock Text="Pescadero Bold*" 

FontFami ly="ms-appx:///Fonts/Pesca.ttf#Pescadero" 
FontWeight="Bold" /> 


<TextBlock Text="Pescadero Italic*" 

FontFami ly="ms-appx:///Fonts/Pesca.ttf#Pescadero" 
FontStyl e="Italic" /> 

</StackPanel> 


</Gri d> 
</Page> 


These FontFomily strings include the ms-appx prefix for referencing embedded content of the 
application file, followed by the Fonts folder and the filename within the Fonts folder. Here’s the URI 
of the Kooten.ttf file: 


ms-appx:///Fonts/Kooten.ttf 
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It’s possible to remove the "ms-appx:///" prefix and the program will work the same. 

The URI is followed by a hash sign, and the family name of the font in this font file: 

FontFami 1 y="ms-appx:///Fonts/Kooten.ttf#Kootenay" 

Obviously, this font family name is not the name of the file (but it could be). To obtain the font family 
name of an arbitrary TrueType font file not stored in the /Windows/Fonts directory, you can right-click 
the font file in Windows Explorer and choose Properties or Preview. 

The Miramo.ttf file is the regular version of Miramonte; the bold version is in the Miramob.ttf file. 
Notice that in both cases the font family name specified in the markup is "Miramonte." If these two 
font files were installed under Windows, you’d reference either of them by setting the FontFomily 
attribute to "Miramonte”，and you’d get the bold version by setting FontWeight to Bold. When you’re 
using the syntax that includes the font file, the font family name is the same but you don’t need to set 
FontWeight. 

Similarly, the Peric.ttf file has the regular Pericles font and Pericl.ttf file contains the Light version; 
the regular Pescadero font is in Pesca.ttf, while the Bold version is in Pescab.ttf. 

Notice that the last two TextBlock elements both reference the file containing the regular version 
of Pescadero, but the FontWeight and FontStyle attributes are set to Bold and Italic, respectively. 
Because these attributes are applied to a regular font, these styles are simulated, as I indicate with an 
asterisk and footnote. 

The PrivateFonts program actually displays four columns of text. Here’s only the first column 
generated from the XAML you’ve just seen: 


Kootenay 

Miramonte 

Miramonte Bold 

Pericles 

Pericles Light 

Pescadero 
Pescadero Bold 
Pescadero Bold* 

Pescadero Italic* 


^simulated 

Notice how the actual boldface font is different from the simulated boldface. (Also, notice how the 
Pericles font displays lowercase letters with small capitals!) 
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To reference a private font in code, you create a FontFomily object by using the same string you 
use inXAML: 

txtblk.FontFami1y = new FontFami ly("ms-appx:///Fonts/Linds.ttf#Lindsey") ; 

The PrivateFonts program displays four columns of very similar text, and you've seen only the first, 
so we’re not quite finished with this program. 


A Taste of Glyphs 


An alternative to the Text Block element is an element called Glyphs. It is harder to use than TextBlock, 
but it includes a facility to space individual characters. 

The second column of text in PrivateFonts is displayed with the following markup: 


Project: PrivateFonts | File: MainPage.xaml (excerpt) 

〈Grid Grid.Col umn="l"> 

<Glyphs UnicodeStri ng="Kootenay" 

FontUri="ms-appx:///Fonts/Kooten .ttf" 
FontRenderingEmSi ze="36" 

Fill="Black" 

OriginX= M 0" 

OriginY="45 M /> 

<Glyphs UnicodeStri ng="Li ndsey" 

FontUri="ms-appx:///Fonts/Li nds.ttf" 
FontRenderingEmSi ze="36" 

Fill= M Black" 

OriginX= M 0" 

0riginY="90" /> 

<Glyphs UnicodeStri ng="Mi ramonte" 

FontUri ="ms-appx:///Fonts/Miramo.ttf" 
FontRenderingEmSi ze="36" 

Fill= M Black" 

OriginX= M 0" 

OriginY="135" /> 

<Glyphs UnicodeStri ng="Mi ramonte Bold" 

FontUri ="ms-appx:///Fonts/Mi ramob.ttf" 
FontRenderingEmSi ze="36" 

Fill= M Black" 

OriginX="0" 

0riginY="180" /> 

<Glyphs UnicodeStri ng="Peri cles" 

FontUri="ms-appx: ///Fonts/Peric■ttf" 
FontRenderingEmSi ze="36" 

Fill="Black" 

OriginX="0" 

OriginY="225" /> 
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<Glyphs UnicodeStri ng="Peri cles Light" 

FontUri="ms-appx:///Fonts/Peri cl .ttf" 
FontRenderingEmSi ze="B6" 

Fill= M Black" 

OriginX="0" 

0riginY="270" /> 

<Glyphs UnicodeStri ng="Pescadero" 

FontUri="ms-appx:///Fonts/Pesca. ttf" 
FontRenderingEmSi ze="B6" 

Fill= M Black" 

OriginX="0" 

OriginY="315" /> 

<Glyphs UnicodeStri ng="Pescadero Bold" 

FontUri="ms-appx:///Fonts/Pescab. ttf" 
FontRenderingEmSi ze="36" 

Fill="Black" 

OriginX="0" 

0riginY="360" /> 

<Glyphs UnicodeStri ng="Pescadero Bold*" 

FontUri="ms-appx:///Fonts/Pesca. ttf" 
StyleSimulati ons="Bol dSimulati on" 
FontRenderingEmSi ze="B6" 

Fill="Black" 

OriginX="0" 

0riginY="405" /> 

<Glyphs UnicodeStri ng="Pescadero Italic*” 

FontUri="ms-appx:///Fonts/Pesca. ttf" 
StyleSimulati ons="Ital icSimulation" 
FontRenderingEmSi ze="B6" 

Fill="Black" 

OriginX="0" 

0n'ginY="450" /> 

</Grid> 


Rather than a Text property, Glyphs defines a UnicodeString property. Three other properties are 
required: The FontUri property is (as the name suggests) a URI of the font file. Notice that it’s only the 
URI; there is no need to supply the font family name. Glyphs works at a low level with the font file; it 
doesn’t know about family names. The FontRenderingEmSize is equivalent to the Font Size property, 
but there is no default. Nor is there a default for the Fill property. 

Notice that the last two items reference the regular Pescadero font file but set StyleSimulotions to 
BoldSimulotion and ItalicSimulation, respectively. The StyleSimulotions enumeration also includes a 
BoldltalicSimulotion member. 

The OriginX and OriginY properties indicate the location of the text relative to its parent — or, more 
precisely, relative to where the parent places the element. The parent here is simply a single-cell Grid 
rather than a StockPanel as I used for the first column. (Very often the parent of a collection of Glyphs 
elements is a Canvas.) The origin specifies the left of the baseline, not the top of the text. I've simply 
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set the first OriginY to 45 and incremented each by 45, which is approximately correct, as you can see 
with a visual comparison of the first two columns displayed by PrivateFonts: 


Kootenay 

L\v\dse^ 

Miramonte 


Kootenay 

Miramonte 


Miramonte Bold 

Pericles 


Miramonte Bold 

Pericles 


Pericles Light 

Pescadero 


Pericles Light 

Pescadero 


Pescadero Bold 
Pescadero Bold* 

Pescadero Italic* 


Pescadero Bold 
Pescadero Bold* 

Pescadero Italic* 


*simulated 


In a real program, you would be using font metrics to position each Glyphs element. 

If you need to set the FontUri property in code, just create a Uri object and use the same string 
that you’ve seen in the XAML file: 

glyphs.FontUri = new Uri ("ms-appx:///Fonts/Linds.ttf") ; 

The Glyphs element does not automatically wrap text in multiple lines. However, there is a 
property not shown in my examples called Indices that lets you provide additional offsets to space 
the individual characters with great precision. You can also use the Indices string to indicate substitute 
characters, such as ligatures, which are stylistic combinations of two or more letters in a single glyph. 


Font Files in Local Storage 


The Glyphs element is found most commonly in documents created using the XML Paper 
Specification (XPS) that Microsoft developed in connection with WPF. XPS is a fixed-page document 
format. That is, all the pages of the document are fixed in size and layout, much like Adobe Portable 
Document Format (PDF). 

A file containing an XPS document is a "package," which is basically a ZIP file containing font files, 
bitmaps, and separate files for each page of the document. Each page of the document is a XAML file 
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with a root element of Fixed Page (a class not defined in the Windows Runtime), generally containing 
some Path elements for displaying graphics and bitmaps in the form of ImageBrush objects and con¬ 
taining Glyphs elements for displaying text. The Glyphs elements have their FontUri attributes set to a 
URI referencing a font file in the XPS package. These Glyphs elements already have all their properties 
set to correctly position the text within the page. 

A WPF program can render an XPS file without too much bother. A Windows 8 program would 
have considerably more work to do. The program would need to open up the XPS package and parse 
the individual FixedPage files. For each page, the program would need to instantiate the various Path, 
ImageBrush, and Glyphs objects in code — all the time taking care to compensate for any XPS features 
not supported under the Windows Runtime. 

Within the XPS package, the URIs of the ImageBrush and Glyphs elements reference bitmap files 
and font file within the package. These bitmaps and font files would need to be copied to application 
local storage, and the URIs modified to point to that storage. 

The PrivateFonts program demonstrates the feasibility of this process. The first time you run the 
program, the third column displays text using the Windows 8 default font rather than any of the 
private fonts and the fourth column is absent: 


Kootenay 

Kootenay 

Kootenay 



Lindsey 

Miramonte 

Miramonte 

Miramonte 

Miramonte Bold 

Miramonte Bold 

Miramonte Bold 

Pericles 

Pericles 

Pericles 

Pericles Light 

Pericles Light 

Pericles Light 

Pescadero 

Pescadero 

Pescadero 

Pescadero Bold 

Pescadero Bold 

Pescadero Bold 

Pescadero Bold* 

Pp.sr.adpro Bold* 

Pescadero Bold* 

Pescadero Italic* 

„ , r ★ Pescadero Italic* 

Pescadero Italic 

^simulated 
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The subsequent times you run the program, the third and fourth columns match the first two: 


Kootenay 

Uv\clsc\\ 

Miramonte 

Miramonte Bold 

Pericles 

Pericles Light 

Pescadero 
Pescadero Bold 
Pescadero Bold* 

Pescadero Italic* 


Kootenay 

LWseq 

Miramonte 

Miramonte Bold 

Pericles 

Pericles Light 

Pescadero 
Pescadero Bold 
Pescadero Bold* 

Pescadero Italic* 


Kootenay 

L\v\dsc\] 

Miramonte 

Miramonte Bold 

Pericles 

Pericles Light 

Pescadero 
Pescadero Bold 
Pescadero Bold* 

Pescadero Italic* 


Kootenay 

LWseq 

Miramonte 

Miramonte Bold 

Pericles 

Pericles Light 

Pescadero 
Pescadero Bold 
Pescadero Bold* 

Pescadero Italic* 


^simulated 


This difference is a fluke based on the structuring of the program. What happens when you first 
run the program is that the font files are copied to application local storage: 


Project: PrivateFonts I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 
{ 

public MainPageC) 

{ 

this .InitializeComponent(); 

Loaded += OnLoaded; 

} 

async void OnLoaded(object sender, RoutedEventArgs args) 

{ 

StorageFolder local Folder = ApplicationData. Current.LocalFolder; 
bool folderExists = false; 

try 

StorageFolder fontsFolder = await localFolder.GetFolderAsync(" Fonts") ; 
folderExists = true; 

} 

catch (Exception) 

{ 

} 

if (!folderExists) 

{ 

StorageFolder fontsFolder = await localFolder.CreateFolderAsync(" Fonts") ; 


string [] fonts = { "Kooten.ttf" , "Linds.ttf" , "Miramo.ttf" , "Miramob.ttf" , 

"Peric.ttf", "pericl•ttf" ， "Pesca.ttf" , "Pescab.ttf" }; 
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foreach (string font in fonts) 

{ 

// Copy from application content to IBuffer 
string uri = "ms-appx:///Fonts/" + font; 

IBuffer buffer = await PathlO. ReadBufferAsync(uri); 

// Copy from IBuffer to local storage 

StorageFi 1 e fontFi 1e = await fontsFolder.CreateFileAsync(font); 
await Fi1elO. WriteBufferAsync(fontFi1e, buffer); 



The Loaded handler checks if a directory named Fonts exists in local storage. If not, it creates 
one and then copies all the font files into that directory with the same names. (If this job could be 
performed synchronously, I would have done it in the constructor prior to InitiolizeComponent so that 
the files would be available to the XAML parser the first time the program is run.) 

The markup for referencing the files in local storage is pretty much the same as referencing 
program content except the prefix is ms-oppdato and the Fonts directory needs to be preceded with 
local. I’m sure you don’t need to see them all to get the general idea: 


Project: PrivateFonts | File: MainPage.xaml (excerpt) 


〈Page … FontSi ze="36"> 

<Grid Background="{Stati cResource 
<Grid.ColumnDefini ti ons> 

<ColumnDefinition Width=" 
<ColumnDefinition Width=" 
<ColumnDefinition Width=" 
<ColumnDefinition Width=" 


ApplicationPageBackgroundThemeBrush}"> 


/> 

々'' /> 
々、' /> 
/> 


</Grid.ColumnDefinitions> 


〈StackPanel Grid.Column="2"> 

<TextBlock Text="Kootenay" 

FontFami1 y="ms-appdata:///local/Fonts/Kooten.ttf#Kootenay" /> 


cTextBlock Text="Pescadero Italic*” 

FontFami1 y="ms-appdata:///local/Fonts/Pesca.ttf#Pescadero" 
FontStyl e="Ital ic" /> 

</StackPanel> 


<Crid Grid.Col umn="3"> 

<Glyphs UnicodeStri ng="Kootenay" 

FontUri="ms-appdata: ///local/Fonts/Kooten.ttf" 
FontRenderingEmSi ze="36" 

FilW'Black" 

OriginX="0" 

OriginY= M 45" /> 
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<Glyphs UnicodeStri ng="Pescadero Italic*" 

FontUri ="ms-appdata:///local/Fonts/Pesca.ttf" 
StyleSimulati ons="Ital icSimulation" 
FontRenderingEmSi ze="36" 

Fill= M Black" 

Origi nX="0" 

0riginY="450" /> 

</Gri d> 


<TextBlock Text="*simul ated" 

Grid.Col umnSpan="4" 

VerticalAli gnment="Bottom" 

HorizontalAli gnment="Center" /> 

</Gri d> 

</Page> 

Again, if you need to do this in code, you'll be using the same strings you’ve seen in the XAML file: 
txtblk.FontFami1y = new FontFami ly("ms-appdata:///local/Fonts/Linds.ttf#Lindsey") ; 
glyphs.FontUri = new Uri ("ms-appdata:///local/Fonts/Linds.ttf") ; 

Of all the sophisticated document formats in existence that might be rendered under Windows 8, 
XPS is almost certainly the easiest because the contents are similar to elements found in the Windows 
Runtime, all the pages have already been constructed, and all the graphics and Glyphs elements have 
been positioned precisely within those pages. Much more challenging would be a reflow-page format 
like EPUB, where the job of positioning words on the page is the responsibility of the program. This 
job requires a more intimate familiarity with font metrics. 

The simple approach to font metrics involves subjecting a TextBlock to a Measure call and 
obtaining its width and height. This would allow you to determine the placement of individual words 
in a paragraph, where lines break within a paragraph, and where paragraphs break between pages. 
However, if you ever need to align separate TextBlock elements of different font sizes or font families 
on the baseline, you’ll need more information. 

At that point, you’ll need to either examine the internals of the font files themselves to extract font 
metrics or begin using DirectWrite. Once you start using DirectWrite for font metrics, quite possibly 
you’ll also see that it's the best tool for laying out pages as well. 


Typographical Enhancements 


The Typography class in the Windows.Ul.Xaml.Documents namespace contains nothing but a 
collection of attached properties for enhancing text. You can insert these attached properties in the 
root element of a page or in a TextBlock or Run element to control various aspects of how text is 
displayed. The catch is: You can’t guarantee that these features work for all fonts. Indeed, you might 
find yourself searching a long time for a font that responds to some of these attached properties! 
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In the following examples, I’ve relied heavily on the documentation of the WPF version of the 
Typography class, which matches up some of these attached properties with particular fonts. Some of 
these examples involve the Lindsey, Miramonte, Pescadero, and Pericles fonts, which are included as 
program content: 

Project: TypographyDemo I File: MainPage.xaml (excerpt) 

<Page … > 

<Page.Resources> 

<Style TargetType="TextBlock"> 

〈Setter Property="FontSi ze" Value="48" /> 

〈Setter Property="Margi n" Value="6 6 6 0" /> 

</Style> 

</Page.Resources> 


<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<StackPanel > 

<TextBlock Text="Smal 1 Caps are Nice for Titles" 

Typography.Capital s=" Small Caps" /> 


<TextBlock Text="Some random contextual alternates make script look more natural 
FontFami1 y="ms-appx:///Fonts/Linds.ttf#Lindsey" 

Typography.Contextual Alternates="True" /> 

〈TextBlock Text="Stacked fractions: 1/2 1/4 1/8 1/3 2/3" 

FontFami ly="Palati no Li notype" 

Typography.Fraction=" Stacked" /> 

<TextBlock Text="Hi storical forms : Four score and seven years ago" 

FontFami ly="Palati no Li notype" 

Typography.HistoricalForms="T rue" /> 


〈TextBlock Text="Numeral alignment for tables: 0123456789" 

FontFami1 y="ms-appx:///Fonts/Miramo.ttf#Mi ramonte" 
Typography.NumeralA1i gnment="Tabular" /> 

<TextBlock Text="01 d-style numbers : 0123456789" 

FontFami ly="Palati no Li notype" 

Typography.NumeralStyl e="01 dStyle" /> 

<TextBlock Text="Standard Swashes With The Pescadero Font" 

FontFami ly="ms-appx:///Fonts/Pesca.ttf#Pescadero" 
Typography.StandardSwashes="l" /> 


<TextBlock Text="Sl ashed Zero: 0" 

FontFami1 y="ms-appx:///Fonts/Miramo.ramonte" 
Typography.SlashedZero="T rue" /> 

〈TextBlock Text="STYLISTIC ALTERNATES WITH THE PERICLES FONT" 
FontFami ly="ms-appx:///Fonts/Peric.ttf#Peri cles" 
Typography.StylisticAl ternates="l" /> 
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<TextBlock FontFami1 y=" Palatino Linotype"> 

Sucrose is C<Run Typography.Vari ants="Inferior">12</Run 
>H<Run Typography.Vari ants="Inferior">22</Run 
>0<Run Typography.Vari ants="Inferior">ll</Run> 

</TextBlock> 

</StackPanel> 

</Gri d> 

</Page> 


And here’s the result: 


Small Caps are Nice for Titles 

^bW\t rav\dovv\ oo^cY^iAal ^l+erm+es w\a^cc 十 look ： w\orc via 十 aral 

Stacked fractions: i i i i i 

Hiftorical formf: Four {core and feven yearf ago 

Numeral alignment for tables: 0123456789 

Old-style numbers: 0123456789 

Standard SwashesAVith The^Pescadero^Font 

Slashed Zero: 0 

STYLISTIC ALT(RNAT6 WITH THC P^RICUS FONT 

Sucrose is C12H22O11 


RichTextBlock and Paragraphs 


Although TextBlock continues to be preferred for text up to a paragraph in length, the RichTextBlock 
offers several enhancements. RichTextBlock does not have a Text property; nor does it have an Inlines 
property for specifying text in the form of Inline derivatives. What RichTextBlock defines instead is 
a property named Blocks, which is a collection of Block derivatives. Like Inline, Block derives from 
TextElement, from which it acquires a bunch of text-related properties. In addition, Block defines 
these properties: 

• LineHeight 

• LineStockingStrotegy 

• Margin 

• TextAlignment 
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Also, like Inline, Block itself is not instantiable. The only class that currently derives from Block is 
Paragraph, which defines two properties: 

• Inlines, a collection of Inline derivatives, and 

• Textlndent, for setting an indentation of the first line of the paragraph. 

So, basically, a RichTextBlock is a collection of paragraphs. The Margin property is useful for defining 
space between the paragraphs, and Textlndent can indent the first line. 

The MadTeaParty project uses a RichTextBlock inside a ScrollViewer to let you peruse Chapter 7 of 
Lewis Car roll's Alice's Adventures in Wonderland, including three of John Tenniel’s illustrations. Here’s 
an excerpt of the XAML file: 


Project: MadTeaParty I File: MainPage.xaml (excerpt) 

<Page … > 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

〈ScrollViewer Wi dth="720" 

Padding="40 20"> 

<!-- Text and images from http : //ebooks.adelaide.edu.au/c/carrol1/Iewis/alice/ --> 

<RichTextBlock FontFami1 y="Cambria" 

FontSi ze="24"> 

〈Paragraph Margi n="0 12" TextAli gnment="Center" FontSi ze="40"> 

<Itali c>Al ice's Adventures in Wonderl and</Ital ic> 

<LineBreak/> 
by 

<LineBreak/> 

Lewis Carrol 1 
</Paragraph> 

〈Paragraph Margi n="0 24 0 36" TextAli gnment="Center" FontSi ze="30"> 

Chapter VII 
<LineBreak /> 

A Mad Tea-Party 
</Paragraph> 

〈Paragraph Margi n="0 6"> 

There was a table set out under a tree in front of the 
house, and the March Hare and the Hatter were having tea at 
it: a Dormouse was sitting between them, fast asleep, and 
the other two were using it as a cushion, resting their 
el bows on it, and talking over its head. ‘Very uncomfortable 
for the Dormouse,* thought Alice; 1 only, as it’s asleep, I 
suppose it doesn’t mind.* 

</Paragraph> 


〈Paragraph Margi n="0 6" Textlndent="48"> 

The table was a large one, but the three were all crowded 

together at one corner of it: 1 No room! No room!* they 

cried out when they saw Alice coming. ‘There’s 

<Itali c>pl enty</Ital ic> of room!* said Alice indignantly, 

and she sat down in a large arm-chair at one end of the table. 

</Paragraph> 
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〈Paragraph Margin :”。 6” Textlndent="48"> 

‘Have some wine，’ the March Hare said in an encouraging tone. 
</Paragraph> 

〈Paragraph Margin :"。 6" Textlndent="48"> 

Alice looked all round the table, but there was nothing on it 
but tea. ‘I don’t see any wine,’ she remarked. 

</Paragraph> 

〈Paragraph Margin :"。 6" Textlndent="48"> 

‘There isn’t any,* said the March Hare. 

</Paragraph> 


〈Paragraph Margin="0 6" Textlndent="48"> 

‘It 

<Itali c>i s</Italic> the same thing with you,* said the 
Hatter, and here the conversation dropped, and the party sat 
silent for a minute, while Alice thought over all she could 
remember about ravens and writing-desks, which wasn’t much. 

</Paragraph> 

〈Paragraph Margin="0 6" TextAli gnment="Center"> 

<InlineUIContainer> 

<Image Source="Images/ChapterVII-l. png" Stretch="None" /> 
</InlineUIContainer> 

</Paragraph> 

〈Paragraph Margin :”。 6 n Textlndent="48"> 

The Hatter was the first to break the silence. ‘What day of 
the month is it?* he said, turning to Alice: he had taken 
his watch out of his pocket, and was looking at it uneasily ， 
shaking it every now and then, and holding it to his ear. 

</Paragraph> 


〈Paragraph Margin :"。 6" Textlndent="48"> 

Just as she said this, she noticed that one of the trees 
had a door leading right into it. ‘That’s very curious!’ 
she thought. ‘But everything’s curious today. I think I 
may as well go in at once.* And in she went. 

</Paragraph> 

〈Paragraph Margin :"。 6" Textlndent="48"> 

Once more she found herself in the long hall ， and close to 
the little glass table. 'Now, I'll manage better this time, 
she said to herself, and began by taking the little golden 
key, and unlocking the door that led into the garden. Then 
she went to work nibbling at the mushroom (she had kept a 
piece of it in her pocket) till she was about a foot high: 
then she walked down the little passage : and 
<Itali c>then</Ital ic> - she found herself at last in the 
beautiful garden, among the bright flower-beds and the cool 
fountains. 
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</Paragraph> 

</RichTextBlock> 

〈 /ScrollViewer> 

</Grid> 

</Page> 

Paragraph doesn't derive from FromeworkElement, so it doesn’t have a Style property. If you want 
to set the same properties on a bunch of Paragraph objects, they need to be explicit. Most of the 
paragraphs in "A Mad Tea-Party” have a Margin property for a 12-pixel interparagraph spacing and a 
Textlndent property to indent the first line 48 pixels. 

The InlineUIContainer doesn't work with TextBlock, but it does with RichTextBlock. This allows you 
to embed a UlElement derivative in text. The possibilities include Text Block, so this facility provides 
a way to embed text in a paragraph that contains a binding on its Text property. However, this 
embedded TextBlock element can't itself wrap text. 

In the MadTeaParty program, the Image elements become part of the RichTextBlock. This requires 
that they go inside an InlineUIContainer object, which then needs to be inside a Paragraph. There is 
no facility to wrap the text of a paragraph around an image. If you want to do something like that 
with C# and XAML, you’ll need to start measuring individual words of text and positioning them 
yourself. 

Here’s the chapter scrolled down to a point where you can see the third of the three images: 


she got up in great disgust, and walked off; the Dormouse fell 
asleep instantly, and neither of the others took the least notice 
of her going, though she looked back once or twice, half 
hoping that they would call after her: the last time she saw 
them, they were trying to put the Dormouse into the teapot. 



’At any rate I’ll never go there again!’ said Alice as she 
picked her way through the wood. 'It’s the stupidest tea-party 
I ever was at in all my life!’ 
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RichTextBlock Selection 


When the MadTeaParty program is running, tap a word with your finger. The word is selected with 
two circular handles at each end. You can then grab those handles and extend the selection. Tap the 
selection and a little menu comes up to copy the selection to the clipboard. 

Or, if you don’t have a touch screen, use the mouse with the button pressed to select some text. 
Then right-click to bring up the context menu with the Copy item. 

RichTextBlock implements a SelectionChongecJ event, a SelectedText property to obtain the selected 
text — but not to replace it or delete it — and SelectionStort and SelectionEnd properties. These latter 
two properties are of type 丁 ext Pointer, which not only provides an offset of the selected text within 
the TextBlock but also indicates the pixel location of the selection relative to the TextBlock. 

There is also a ContextMenuOpening event that occurs right before the context menu is displayed. 
If you set the Handled property of the event arguments to true, the menu is not displayed, which 
means that you can display your own context menu. 

If you'd prefer that the RichTextBlock not allow text to be selected, set IsTextSelectionEnabled to 
false. 

RichTextBlock and Overflow 


Throughout the history of books and reading, there have been two basic ways of presenting 
extended text: a scroll of continuous text — common in ancient Egypt, China, and the Mediterranean 
cultures of Greece and Rome — or a collection of individual pages, a form that began emerging in 
Europe during the first several centuries of the common era. 

These two formats are also common on the computer: Most webpages use scrolling, but most e- 
book readers separate the text into pages. 

IVe just demonstrated that RichTextBlock can present text that is scrolled, but RichTextBlock takes a 
giant step beyond previous text-display elements by its ability to paginate a document. These pages 
can then be displayed sequentially, as in an e-book reader, or displayed in adjacent columns. 

Here’s how it works: You put all the text you want to display in a RichTextBlock and then give 
it a finite size, which means to subject it to a Measure pass, either manually or as part of normal 
page layout. If the RichTextBlock contains more text than it can display in the space allotted for 
it, its HosOverflowContent property becomes true. To display the second page of text beyond the 
RichTextBlock, create an instance of the Rich Text BI ockO verflo w class and set that instance to the 
OverflowContentTarget property of the RichTextBlock. 

RichTextBlockOverflow also defines HosOverflowContent and OverflowContentTarget properties, 
so you can create additional RichTextBlockOverflow objects for each additional page and string them 
in a chain. The RichTextBlockOverflow elements inherit all the text-related properties — FontFamily, 
Font Size, and so forth — from the parent RichTextBlock. 
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If you can estimate the maximum number of pages you’ll need to display a document, you can 
do this chaining job entirely in XAML by using data bindings. The YoungGoodmanBrown project 
demonstrates how it’s done. The text is Nathaniel Hawthorne’s unnerving short story "Young 
Goodman Brown” that I lifted from Project Gutenberg. Just as for "A Mad Tea-Party,” I put the entire 
text in a single RichTextBlock, but I gave the OverflowContentTorget property of that RichTextBlock to 
a RichTextBlockOverflow element, and so on down the chain: 


Project: YoungGoodmanBrown I File: MainPage.xaml (excerpt) 

<Page … > 

<Page.Resources 〉 

<1ocal : BooleanToVisibi1ityConverter x : Key="bool eanToVisibi1ity" /> 

<Style TargetType="Ri chTextBlock"> 

〈Setter Property="Wi dth" Value="480" /> 

〈Setter Property="Margi n" Value="24 0 24 0" /> 

〈Setter Property="FontSi ze" Value="18" /> 

〈Setter Property="TextAl ignment" Val ue=" Justify" /> 

</Style> 


<Style TargetType="Ri chTextBlockOverflow"> 

〈Setter Property="Wi dth" Value="480" /> 

〈Setter Property="Margi n" Value="24 0 24 0" /> 
</Style> 

</Page.Resources 〉 


<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

<ScrollViewer HorizontalScrollBarVisibi1i ty="Hi dden" 

Vertical ScrollBarVisibi1i ty="Di sabl ed"> 

<StackPanel Orientati on="Hori zontal"> 

<!-- Text from http://www.gutenberg.org/files/512/512-h/512-h.htm --> 

<RichTextBlock Name="ri chTextBlock" 

OverflowContentTarget="{Bi nding ElementName=ove rf1 owl}"> 
〈Paragraph TextAli gnment="Center"> 

YOUNG GOODMAN BROWN 
</Paragraph> 


〈Paragraph TextAli gnment="Center" Margi n="0 12"> 
by 

<LineBreak /> 

Nathaniel Hawthorne 
</Paragraph> 


〈Paragraph Margi n="0 6" Textlndent="48"> 

Young Goodman Brown came forth at sunset 'into the street at Salem 
village; but put his head back, after crossing the threshold, to 
exchange a parting kiss with his young wife. And Faith, as the wife was 
aptly named, thrust her own pretty head into the street, "letting the 
wind pi ay with the pink ribbons of her cap while she called to Goodman 
Brown. 

</Paragraph> 
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〈Paragraph Margin:'’ 。 6" Textlndent="48"> 

"Dearest heart," whispered she, softly and rather sadly, when her lips 
were close to his ear, "prithee put off your journey until sunrise and 
sleep in your own bed to-night. A lone woman is troubled with such 
dreams and such thoughts that she’s afeard of herself sometimes. Pray 
tarry with me this night, dear husband, of all nights in the year." 

</Paragraph> 


</Ri chTextBlock> 


<RichTextBlockOve「flow Name="overflowl" 

Vi sibi1i ty="{Binding ElementName=ri chTextBlock, 

Path=HasOve rflowContent, 

Converter={Stati cResource booleanToVisibi1i ty}} 
OverflowContentTarget="{Bi nding El ementName=overfl ow2}" /> 

<RichTextBlockOverflow Name="overflow2" 

Vi sibi1i ty="{Binding El ementName=overf1 owl, 

Path=HasOverfl owContent, 

Converter={Stati cResource booleanToVisibi1i ty}} 
OverflowContentTarget="{Bi nding El ementName=overfl ow3}" /> 

<Ri chTextBl ockOve rfl ow Name="overf"low3" 

Vi sibi1i ty="{Binding El ementName=overfl ow2, 

Path=HasOverf 1owContent, 

Converter={Stati cResource booleanToVisibi1i ty}} 
OverflowContentTarget="{Bi nding El ementName=overfl ow4}" /> 

<RichTextBlockOve rflow Name="overflow4" 

Vi sibi1i ty="{Binding El ementName=overfl ow3, 

Path=HasOve rflowContent, 

Converter={Stati cResource booleanToVisibi1i ty}} 
OverflowContentTarget="{Bi nding El ementName=overfl ow5}" /> 

<RichTextBlockOve rflow Name="overflow5" 

Vi sibi1i ty="{Binding El ementName=overfl ow4, 

Path=HasOverfl owContent, 

Converter={Stati cResource booleanToVisibi1i ty}} 
OverflowContentTarget="{Bi nding El ementName=overfl ow6}" /> 

<RichTextBlockOve rflow Name="overflow6" 

Vi sibi1i ty="{Binding El ementName=overfl ow5, 

Path=HasOverfl owContent, 

Converter={Stati cResource booleanToVisibi1i ty}} 
OverflowContentTarget="{Bi nding El ementName=overfl ow7}" /> 

<RichTextBlockOve rflow Name="overflow7" 

Vi sibi1i ty="{Binding El ementName=overfl ow6, 

Path=HasOverfl owContent, 

Converter={Stati cResource booleanToVisibi1i ty}} 
OverflowContentTarget="{Bi nding El ementName=overfl ow8}" /> 

<RichTextBlockOve rflow Name="overflow8" 

Vi sibi1i ty="{Binding El ementName=overfl ow7, 

Path=HasOverfl owContent, 

Converter={Stati cResource booleanToVisibi1i ty}} 
OverflowContentTarget="{Bi nding El ementName=overfl ow9}" /> 
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<RichTextBlockOverflow Name="overfl ow9" 

Vi sibi1i ty="{Binding El ementName=overfl ow8 ， 

Path=HasOverfl owContent, 

Converter={Stati cResource booleanToVisibi1i ty}}" 
OverflowContentTarget="{Bi nding El ementName=overflowlO}" /> 

<RichTextBlockOverf1ow Name="ove rf1owlO" 

Vi sibi1i ty="{Binding El ementName=overfl ow9 ， 

Path=HasOverfl owContent, 

Converter={Stati cResource booleanToVisibi1i ty}}" 
OverflowContentTarget="{Bi nding El ementName=overflowll}" /> 

<RichTextBlockOverflow Name="overfl owll" 

Vi sibi1i ty="{Binding El ementName=overfl owlO, 

Path=HasOverfl owContent, 

Converter={Stati cResource booleanToVisibi lity}}" 
OverflowContentTarget="{Bi nding El ementName=overflowl2}" /> 

<RichTextBlockOve rf1ow Name="ove rf1owl2" 

Vi sibi1i ty="{Binding El ementName=overfl owll, 

Path=HasOverfl owContent ， 

Converter={Stati cResource booleanToVisibi1i ty}}" 
OverflowContentTarget="{Bi nding El ementName=overflowl3}" /> 

<RichTextBlockOverflow Name="overfl owl3" 

Vi sibi1i ty="{Binding El ementName=overfl owl2 ， 

Path=HasOverfl owContent, 

Converter={Stati cResource booleanToVisibi1i ty}}" 
OverflowContentTarget="{Bi nding El ementName=overflowl4}" /> 

<RichTextBlockOve rf1ow Name="ove rf1owl4" 

Vi sibi1i ty="{Binding El ementName=overfl owl3 ， 

Path=HasOverfl owContent, 

Converter={Stati cResource booleanToVisibi1i ty}}" 
OverflowContentTarget="{Bi nding El ementName=overflowl5}" /> 

<RichTextBlockOverflow Name="overfl owl5" 

Vi sibi1i ty="{Binding El ementName=overfl owl4 ， 

Path=HasOverfl owContent, 

Converter={Stati cResource booleanToVisibi1i ty}}" 
OverflowContentTarget="{Bi nding El ementName=overflowl6}" /> 

<RichTextBlockOve rf1ow Name="overflowl6" 

Vi sibi1i ty="{Binding El ementName=overfl owl5, 

Path=HasOverfl owContent, 

Converter={Stati cResource booleanToVisibi1i ty}}" 
OverflowContentTarget="{Bi nding El ementName=overflowl7}" /> 

<RichTextBlockOverflow Name="overfl owl7" 

Vi sibi1i ty="{Binding El ementName=overfl owl6, 

Path=HasOverfl owContent, 

Converter={Stati cResource booleanToVisibi1i ty}}" 
OverflowContentTarget="{Bi nding El ementName=overflowl8}" /> 
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<RichTextBlockOverf1ow Name="overflowl8" 

Vi sibi1i ty="{Binding El ementName=overfl owl7 ， 

Path=HasOverfl owContent, 

Converter={Stati cResource booleanToVisibi1i ty}}" 
OverflowContentTarget="{Bi nding El ementName=overfl owl9}" /> 

<RichTextBlockOve rf1ow Name="overflowl9" 

Vi sibi1i ty="{Binding El ementName=overfl owl8, 

Path=HasOverfl owContent, 

Converter={Stati cResource booleanToVisibi1i ty}}" 
OverflowContentTarget="{Bi nding El ementName=overfl ow20}" /> 

<RichTextBlockOve rf1ow Name="overflow20" 

Vi sibi1i ty="{Binding El ementName=overfl owl9, 

Path=HasOverfl owContent, 

Converter={Stati cResource booleanToVisibi1i ty}}" 
OverflowContentTarget="{Bi nding El ementName=overfl ow21}" /> 

<RichTextBlockOve rf1ow Name="overflow21" 

Vi sibi1i ty="{Binding ElementName=ove rf1ow20, 

Path=HasOve rflowContent, 

Converter={Stati cResource booleanToVisibility}}" /> 

</StackPanel> 

</ScrollViewer> 

</Gri d> 

</Page> 


Each RichTextBlockOverflow is hidden if the previous one doesn't have any overflow content, 
and each except the very last spills its overflow content into the next one through a binding. All the 
RichTextBlockOverflow elements share a horizontal StackPanel in a ScrollViewer with the original 
RichTextBlock, so the text forms columns that can be horizontally scrolled: 


YOUNG GOODMAN BROWN 
by 

Nathaniel Hawthorne 

Young Goodman Brown came forth at sunset into the street 
at Salem village; but put his head back, after crossing the 
threshold, to exchange a parting kiss with his young wife. 
And Faith, as the wife was aptly named, thrust her own 
pretty head into the street, letting the wind play with the 
pink ribbons of her cap while she called to Goodman Brown. 

"Dearest heart," whispered she, softly and rather sadly, 
when her lips were close to his ear, "prithee put off your 
journey until sunrise and sleep in your own bed to-night. A 
lone woman is troubled with such dreams and such 
thoughts that she's afeard of herself sometimes. Pray tarry 
with me this night, dear husband, of all nights in the year." 

"My love and my Faith," replied young Goodman 
Brown, "of all nights in the year, this one night must I tarry 
away from thee. My journey, as thou cal lest it, forth and 
back again, must needs be done 'twixt now and sunrise. 
What, my sweet pretty wife, dost thou doubt me already, 
and we but three months married?" 

"Then God bless you!" said Faith, with the pink 
ribbons; "and may you find all well when you come back." 

"Amen!" cried Goodman Brown. "Say thy prayers, dear 
Faith, and go to bed at dusk, and no harm will come to 
thee." 

So they parted; and the young man pursued his way 
until, being about to turn the corner by the meeting-house, 
he looked back and saw the head of Faith still peeping after 
him with a melancholy air, in spite of her pink ribbons. 

"Poor little Faith!" thought he, for his heart smote him. 
"What a wretch am I to leave her on such an errand! She 


talks of dreams, too. Methought as she spoke there was 
trouble in her face, as if a dream had warned her what work 
is to be done tonight. But no, no; 't would kill her to think it. 
Well, she's a blessed angel on earth; and after this one night 
I'll cling to her skirts and follow her to heaven." 

With this excellent resolve for the future, Goodman 
Brown felt himself justified in making more haste on his 
present evil purpose. He had taken a dreary road, darkened 
by all the gloomiest trees of the forest which barely stood 
aside to let the narrow path creep through, and closed 
immediately behind. It was all as lonely as could be; and 
there is this peculiarity in such a solitude, that the traveller 
knows not who may be concealed by the innumerable 
trunks and the thick boughs overhead; so that with lonely 
footsteps he may yet be passing through an unseen 
multitude. 

"There may be a devilish Indian behind every tree," 
said Goodman Brown to himself; and he glanced fearfully 
behind him as he added, "What if the devil himself should 
be at my very elbow!" 

His head being turned back, he passed a crook of the 
road, and, looking forward again, beheld the figure of a 
man, in grave and decent attire, seated at the foot of an old 
tree. He arose at Goodman Brown's approach and walked 
onward side by side with him. 

"You are late, Goodman Brown," said he. "The clock of 
the Old South was striking as I came through Boston, and 
that is full fifteen minutes agone." 

"Faith kept me back a while," replied the young man, 
with a tremor in his voice, caused by the sudden appearance 
of his companion, though not wholly unexpected. 

It was now deep dusk in the forest, and deepest in 
that part of it where these two were journeying. As nearly as 


could be discerned, the second t 
years old, apparently in the same t 
Brown, and bearing a considerab 
though perhaps more in expressior 
might have been taken for father a 
the elder person was as simply clac 
simple in manner too, he had an 
who knew the world, and who wou 
at the governor's dinner table or 
were it possible that his affairs she 
the only thing about him that c 
remarkable was his staff, which bor 
black snake, so curiously wrought 
seen to twist and wriggle itself like 
course, must have been an ocular d 
uncertain light. 

"Come, Goodman Brown," c 
"this is a dull pace for the beginnir 
staff, if you are so soon weary." 

"Friend," said the other, exchi 
a full stop, "having kept covenant b; 
my purpose now to return whence 
touching the matter thou wot'st of." 

"Sayest thou so?" replied he 
apart. "Let us walk on, nevertheless, 
if I convince thee not thou shalt t 
little way in the forest yet." 

"Too far! too far!" excl. 
unconsciously resuming his walk. "N 
the woods on such an errand, nor h 
have been a race of honest men ar 
the days of the martyrs; and shall I 
of Brown that ever took this path an 

"Such company, thou wouldst 
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These columns are more readable than text that extends to the full width of the landscape screen. 


Of course, if you don't provide a sufficient number of RichTextBlockOverflow elements, the text 
will be truncated and you’ll never be able to read the end of the story. For that reason, it’s probably 
better to generate the RichTextBlockOverflow elements in code. 

When you create a project of type Grid App or Split App in Visual Studio, you get a 
RichTextColumns class in the Common folder. This class derives from Panel and generates 
RichTextBlockOverflow elements in its MeosureOverride method. 

I’ll show you another approach. Like the two previous projects, the MainPage.xaml file in the next 
project contains a complete text in a RichTextBlock element. This time it 7 s F. Scott Fitzgerald's tale of 
Jazz Age teenagers in "Bernice Bobs Her Hair ”： 


Project: BerniceBobsHerHair I File: MainPage.xaml (excerpt) 

<Page … > 

<Page.Resources 〉 

<Style TargetType="Ri chTextBlock"> 

〈Setter Property="Wi dth" Value="480" /> 

〈Setter Property="Margi n" Value="24 0 24 0" /> 
〈Setter Property="FontSi ze" Value="18" /> 

〈Setter Property="TextAl ignment" Val ue=" Justify" /> 
</Style> 


<Style TargetType="Ri chTextBlockOverflow"> 

〈Setter Property="Wi dth" Value="480" /> 

〈Setter Property="Margi n" Value="24 0 24 0" /> 
</Style> 

</Page.Resources 〉 


<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

<ScrollViewer HorizontalScrollBarVisibi1i ty="Hi dden" 

Vertical ScrollBarVisibi1i ty="Di sabled"> 

<StackPanel Name="stackPanel " 

Orientati on="Hori zontal"> 

<RichTextBlock Si zeChanged="OnRi chTextBlockSizeChanged"> 

〈Paragraph TextAli gnment="Center" FontSi ze="36" Margin="0 0 0 12"> 
"Bernice Bobs Her Hair" 

<LineBreak /> 
by 

<LineBreak /> 

F. Scott Fitzgerald 
</Paragraph> 
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〈Paragraph Margi n="0 6"> 

After dark on Saturday tright one could stand on the first tee of 

the golf-course and see the country-club windows as a yellow 

expanse over a very black and wavy ocean. The waves of this 

ocean, so to speak, were the heads of many curious caddies, a few 

of the more ingenious chauffeurs, the golf professional*s deaf 

sister&#x2014;and there were usually several stray, diffident waves who 

might have rolled insi.de had they so desired. This was the 

gallery. 

</Paragraph> 


〈Paragraph Textlndent="48" Margi n="0 6"> 

Then picking up her staircase she set off at a half-run down the 
moonlit street. 

</Paragraph> 

</RichTextBlock> 

</StackPanel> 

</ScrollViewer> 

</Gri d> 

</Page> 

Notice the SizeChangecJ handler set on the RichTextBlock. That handler begins by getting rid of all 
the previous RichTextBlockOverflow elements it might have created during previous size changes, and 
then it creates a whole new batch: 

Project: BerniceBobsHerHair I File: MainPage.xaml.es (excerpt) 

void OnRichTextBlockSizeChanged (object sender, SizeChangedEventArgs args) 

{ 

RichTextBlock richTextBlock = sender as RichTextBlock; 

if (H chTextBl ock. Actual Height == 0) 
return ; 

// Get rid of all previous RichTextBlockOverflow objects 
while (stackPanel.Children.Count > 1) 
stackPanel.Children.RemoveAt(l); 


if (!richTextBlock.HasOverf1owContent) 
return ; 


// Create first RichTextBlockOverflow 

RichTextBlockOverflow richTextBlockOverflow = new RichTextBlockOverfl ow(); 

richTextBlock.OverflowContentTarget = richTextBlockOverflow; 
stackPanel.ChiIdren.Add(richTextBlockOverflow); 

// Measure it 

richTextBlockOverflow.Measure (new Si ze(richTextBlockOverflow.Width, this .ActualHeight)); 
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// If it has overflow content, repeat the process 
while (richTextBlockOverflow.HasOverflowContent) 


RichTextBlockOverflow newRichTextBlockOverflow = new RichTextBlockOverfl ow(); 

richTextBlockOve rf1ow.Ove rf1owContentTarget = newRichTextBlockOverflow; 
richTextBlockOverflow = newRichTextBlockOverflow; 
stackPanel.Chi 1dren.Add(richTextBlockOverflow); 

richTextBlockOverflow.Measure (new Si ze(richTextBlockOverflow.Width, this .ActualHeight)); 



Notice the calls to the Measure method of RichTextBlock and RichTextBlockOverflow. This is 
necessary to force the element to determine how much text can fit within that rectangle, and to set 
the HosOverflowContent property appropriately. Here’s the result: 


"Bernice Bobs Her Hair" 
by 

F. Scott Fitzgerald 


After dark on Saturday night one could stand on the first tee 
of the golf-course and see the country-club windows as a 
yellow expanse over a very black and wavy ocean. The 
waves of this ocean, so to speak, were the heads of many 
curious caddies, a few of the more ingenious chauffeurs, the 
golf professional's deaf sister — and there were usually 
several stray, diffident waves who might have rolled inside 
had they so desired. This was the gallery. 

The balcony was inside. It consisted of the circle of 
wicker chairs that lined the wall of the combination 
clubroom and ballroom. At these Saturday-night dances it 
was largely feminine; a great babel of middle-aged ladies 
with sharp eyes and icy hearts behind lorgnettes and large 
bosoms. The main function of the balcony was critical, it 
occasionally showed grudging admiration, but never 
approval, for it is well known among ladies over thirty-five 
that when the younger set dance in the summer-time it is 
with the very worst intentions in the world, and if they are 
not bombarded with stony eyes stray couples will dance 
weird barbaric interludes in the corners, and the more 
popular, more dangerous, girls will sometimes be kissed in 
the parked limousines of unsuspecting dowagers. 

But, after all, this critical circle is not close enough to 
the stage to see the actors' faces and catch the subtler 
byplay. It can only frown and lean, ask questions and make 
satisfactory deductions from its set of postulates, such as 
the one which states that every young man with a large 
income leads the life of a hunted partridge. It never really 


appreciates the drama of the shifting, semi-cruel world of 
adolescence. No; boxes, orchestra-circle, principals, and 
chorus be represented by the medley of faces and voices 
that sway to the plaintive African rhythm of Dyer's dance 
orchestra. 

From sixteen-year-old Otis Ormonde, who has two 
more years at Hill School, to G. Reece Stoddard, over whose 
bureau at home hangs a Harvard law diploma; from little 
Madeleine Hogue, whose hair still feels strange and 
uncomfortable on top of her head, to Bessie MacRae, who 
has been the life of the party a little too long — more than 
ten years — the medley is not only the centre of the stage 
but contains the only people capable of getting an 
unobstructed view of it. 

With a flourish and a bang the music stops. The 
couples exchange artificial, effortless smiles, facetiously 
repeat "la-de-da-dadum-dum," and then the clatter of 
young feminine voices soars over the burst of clapping. 

A few disappointed stags caught in midfloor as they 
had been about to cut in subsided listlessly back to the 
walls, because this was not like the riotous Christmas dances 
— these summer hops were considered just pleasantly warm 
and exciting, where even the younger marrieds rose and 
performed ancient waltzes and terrifying fox trots to the 
tolerant amusement of their younger brothers and sisters. 

Warren McIntyre, who casually attended Yale, being 
one of the unfortunate stags, felt in his dinner-coat pocket 
for a cigarette and strolled out onto the wide, semidark 
veranda, where couples were scattered at tables, filling the 
lantern-hung night with vague words and hazy laughter. He 
nodded here and there at the less absorbed and as he 
passed each couple some half-forgotten fragment of a story 
played in his mind, for it was not a large city and every one 
was Who's Who to every one else's past. There, for example. 


were Jim Strain and Ethel Demo rest 
engaged for three years. Every one 
managed to hold a job for more 
would marry him. Yet how bored th< 
wearily Ethel regarded Jim sometir 
why she had trained the vines of 
wind-shaken poplar. 

Warren was nineteen and rati 
his friends who hadn't gone East t 
boys, he bragged tremendously at 
when he was away from it. There 
who regularly made the rounds o 
and football games at Princeton, Ya 
there was black-eyed Roberta Dil 
famous to her own generation a 
Cobb; and, of course, there was 
besides having a fairy I ike face and 
tongue was already justly celebrate 
cart-wheels in succession during th 
dance 3t New Haven. 

Warren, who had grown up 
Marjorie, had long been "crazy ab( 
seemed to reciprocate his feeling w 
she had tried him by her infallible 
gravely that she did not love him. 
she was away from him she forgot 
other boys. Warren found this dis 
Marjorie had been making little trip 
first two or three days after each ai 
heaps of mail on the Harveys' hall t 
various masculine handwritings. To 
during the month of August she I 
cousin Bernice from Eau Claire, and 
see her alone. It was always neces 
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The Perils of Pagination 

Now that weVe seen RichTextBlock and RichTextBlockOverflow take on a couple of short stories, the 
question naturally poses itself: Can this same technique work for a whole novel? 

Let’s try it. But let’s try it for a reasonably short novel, for example, George Eliot’s Silos Morner. 
Rather than displaying columns of text, the SilasMarner program displays actual pages, and it uses a 
FlipView for displaying the RichTextBlock and RichTextBlockOverflow elements. 

It’s amazing how nicely FlipView gives the program the look and feel of an authentic e-book 
reader. Each page can occupy the whole screen (or nearly the whole screen) and you can navigate 
back and forth among the pages with swipes of your finger. In addition, I’ve put a Slider at the bottom 
of the page that provides a visual representation of your progress through the book, and lets you 
navigate to any page very quickly. 

Perhaps more than any other program in this book, SilasMarner is much more suited for portrait 
mode rather than landscape. In landscape, the line lengths are simply too wide to read comfortably, 
as you can see: 
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more numerous than usual; several personages, who would otherwise have been admitted into the parlour and enlarged the opportunity 
of hectoring and condescension for their betters, being content this evening to vary their enjoyment by taking their spirits-and-water 
where they could themselves hector and condescend in company that called for beer. 


CHAPTER VI 

The conversation, which was at a high pitch of animation when Silas approached the door of the Rainbow, had, as usual, been slow and 
intermittent when the company first assembled. The pipes began to be puffed in a silence which had an air of severity; the more 
important customers, who drank spirits and sat nearest the fire, staring at each other as if a bet were depending on the first man who 
winked; while the beer-drinkers, chiefly men in fustian jackets and smock-frocks, kept their eyelids down and rubbed their hands across 
their mouths, as if their draughts of beer were a funereal duty attended with embarrassing sadness. At last Mr. Snell, the landlord, a man 
of a neutral disposition, accustomed to stand aloof from human differences as those of beings who were all alike in need of liquor, broke 
silence, by saying in a doubtful tone to his cousin the butcher— 

"Some folks 'ud say that was a fine beast you druv in yesterday, Bob?" 

The butcher, a jolly, smiling, red-haired man, was not disposed to answer rashly. He gave a few puffs before he spat and replied, "And 
they wouldn't be fur wrong, John." 

After this feeble delusive thaw, the silence set in as severely as before. 

"Was it a red Durham?" said the farrier, taking up the thread of discourse after the lapse of a few minutes. 

The farrier looked at the landlord, and the landlord looked at the butcher, as the person who must take the responsibility of answering. 
"Red it was," said the butcher, in his good-humoured husky treble--"and a Durham it was." 



"Silas Marner" by George Eliot — Page 36 
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Turn it sideways, and the reading experience is rather better: 


"Silas Marner" by George Eliot — Page 39 of 137 


leave off skulking i’ the dark and i' lone places—let 'em come where there's 
company and candles." 

"As if ghos'es _ud want to be believed in by anybody so ignirant!" said Mr. 
Macey, in deep disgust at the farrier's crass incompetence to apprehend the 
conditions of ghostly phenomena. 


CHAPTER VII 

Yet the next moment there seemed to be some evidence that ghosts had a 
more condescending disposition than Mr. Macey attributed to them; for the 
pale thin figure of Silas Marner was suddenly seen standing in the warm 
light, uttering no word, but looking round at the company with his strange 
unearthly eyes. The long pipes gave a simultaneous movement, like the 
antennae of startled insects, and every man present, not excepting even the 
sceptical farrier, had an impression that he saw, not Silas Marner in the flesh, 
but an apparition; for the door by which Silas had entered was hidden by 
the high-screened seats, and no one had noticed his approach. Mr. Macey, 
sitting a long way off the ghost, might be supposed to have felt an 
argumentative triumph, which would tend to neutralize his share of the 
general alarm. Had he not always said that when Silas Marner was in that 
strange trance of his, his soul went loose from his body? Here was the 
demonstration: nevertheless, on the whole, he would have been as well 
contented without it. For a few moments there was a dead silence, Marner's 
want of breath and agitation not allowing him to speak. The landlord, 
under the habitual sense that he was bound to keep his house open to all 
company, and confident in the protection of his unbroken neutrality, at last 
took on himself the task of adjuring the ghost. 

"Master Marner," he said, in a conciliatory tone, "what's lacking to you? 
What's your business here?" 

"Robbed!" said Silas, gaspingly. "I've been robbed! I want the constable— 
and the Justice—and Squire Cass—and Mr. Crackenthorp." 

"Lay hold on him, Jem Rodney," said the landlord, the idea of a ghost 
subsiding; "he's off his head, I doubt. He's wet through." 

Jem Rodney was the outermost man, and sat conveniently near Marner's 
standing-place; but he declined to give his services. 

"Come and lay hold on him yourself, Mr. Snell, if you've a mind," said Jem, 
rather sullenly. "He's been robbed, and murdered too, for what I know," he 
added, in a muttering tone. 

"Jem Rodney!" said Silas, turning and fixing his strange eyes on the 
suspected man. 


"Aye, Master Marner, what do you want wi' me?" said Jem, trembling a 
little, and seizing his drinking-can as a defensive weapon. 



However, I have resisted giving the program a programmatic preference for portrait mode. In a 
real e-book reader — and I’m using the term broadly to describe any facility in a program for read¬ 
ing a large chunk of text — efficient pagination is crucial. Even if the user can’t change the size of the 
screen, most e-book readers allow the user to change fonts or font sizes, and that affects the pagina¬ 
tion of the book. 

When running SilasMarner on a tablet, you can rotate it, try out snap views, and observe firsthand 
how long it takes for the RichTextBlock and RichTextBlockOverflow elements to repaginate the 
document. 

One of the notorious problems of e-book readers involves maintaining and displaying a 
meaningful page number. Any time a document is repaginated, it has a different number of pages. 
The SilasMarner program saves information in local storage that lets you continue reading where 
you last left off, but it doesn’t save a page number for that purpose. Instead, it maintains a fraction 
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calculated by dividing the current page by the total number of pages. This is the only value that is 
maintained between launchings of the program: 

Project: SilasMarner I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

double fractionRead; 

public MainPageO 

{ 

this. InitializeComponent(); 

// Save and reload fraction read 

IPropertySet propertySet = Applicati onData.Current.LocalSettings.Values; 

Application .Current.Suspending += (sender, args)=> 

{ 

propertySet ["FractionRead"] = fractionRead; 

}； 

if (propertySet.ContainsKey ("FractionRead")) 

fractionRead = (doubl e) propertySet ["FractionRead"] ; 



If the new page size isn’t exactly the same as it was when the program last saved this value, you 
won’t end up on exactly the same page, of course, but at least you’ll be close. 

A real e-book reader would probably download books. For this demonstration program, I’ve 
included the Project Gutenberg file as a program resource. Separating this book into paragraphs is 
the responsibility of the code-behind file. 

Thus, there’s no book text in the XAML file. Instead, the XAML file has a FlipView in the center and 
also displays a heading with the book’s title, current page, and page count. This header isn’t strictly 
necessary, of course, but I wanted a clear indication of the number of pages and current page. A Slider 
sits at the bottom: 


Project: SilasMarner I File: MainPage.xaml (excerpt) 

<Page … > 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush} "> 
<Grid.RowDefinitions> 

<RowDefinition Hei ght="Auto" /> 

〈RowDefinition Height="*" /> 

〈RowDefinition Hei ght="Auto" /> 

</Grid.RowDefiniti ons> 


<StackPanel Grid. Row="0" 

Orientati on="Hori zontal" 

HorizontalA1i gnment="Center"> 

<StackPanel.Resources 〉 

〈Style TargetType="TextBlock"> 

〈Setter Property="FontSi ze" Value="24" /> 
</Style> 

</StackPanel.Resources 〉 
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〈TextBlock Text="&#x201C ;Si 1 as Marner«&#x201D; by George Eliot" /> 
<TextBlock Text="&#x00A0 ;&#x2014; Page&#x00A0;" /> 

〈TextBlock Name="pageNumber" /> 

<TextBlock Text="&#x00A0;of«&#x00A0; " /> 

<TextBlock Name="pageCount" /> 

</StackPanel> 


<F1ipView Name="fl ipView" 

Grid.Row="l" 

Background="Whi te" 

Si zeChanged="OnFl ipViewSizeChanged" 

Selecti onChanged="OnFl ipViewSelectionChanged"> 

<F1ipView.ItemsPanel> 

<ItemsPanelTempiate> 

<StackPanel Orientati on="Hori zontal" /> 

</ItemsPanelTemplate> 

</FlipView.ItemsPanel > 

</FlipView> 

<S1ider Name="pageSl ider" 

Grid.Row="2" 

Margin="24 12 24 0" 

Val ueChanged="OnPageSl iderValueChanged" /> 

</Gri d> 

</Page> 

The crucial processing in this program is the SizeChonged handler for the FlipView. Based on 
the size of the FlipView, the program must generate the proper number of RichTextBlockOverflow 
elements. 

The first time this SizeChonged event is fired after the program is launched, the handler must 
access the book file and divide it into paragraphs. In Project Gutenberg plain-text files, each 
paragraph consists of a sequence of lines with hard carriage returns. Paragraphs are delimited by 
blank lines. The handler must process this text in creating Paragraph objects that it adds to the 
RichTextBlock element: 


Project: SilasMarner I File: MainPage.xaml.es (excerpt) 

async void OnFlipViewSizeChanged (object sender, SizeChangedEventArgs args) 

{ 

// Get the size of the FlipView 
Size containerSize = args.NewSize; 

// Actual value gets modified during processing here, so save it 
double saveFractionRead = fractionRead; 


// First time through after program is launched 
if (f1ipView.Items.Count == 0) 

{ 

// Load book resource 
ILi st<string> bookLines = 

await PathlO. ReadLinesAsync ("ms-appx:///Books/pg550.txt" , 

UnicodeEncoding .Utf8); 
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// Create RichTextBlock 

RichTextBlock richTextBlock = new RichTextBlock 

{ 

FontSize = 22, 

Foreground = new SolidColorBrush (Colors. Black) 


// Create paragraphs 

Paragraph paragraph = new Paragraph 。； 

paragraph.Margin = new Thi ckness(12); 
richTextBlock.Blocks.Add(paragraph); 

foreach (stri ng line in bookLines) 

{ 

// End of paragraph, make new Paragraph 
if (line.Length == 0) 

{ 

paragraph = new ParagraphC) ; 
paragraph.Margin = new Thi ckness(12); 
richTextBlock.Blocks.Add(paragraph); 

} 

// Continue the paragraph 
else 
{ 

string textLine = line; 

char 1astChar = line[line.Length - 1]; 

if (lastChar != ‘‘） 
textLine ; 

if (1 ine[0]== ‘‘） 

paragraph. Ini i nes .Add (new Li neBreakO) ; 
paragraph.Iniines. Add(new Run { Text = textLine }); 

} 

} 

// Make RichTextBlock the same size as the FlipView 
flipView.Items.Add(richTextBlock); 
richTextBlock.Measure(containerSize); 

// Generate RichTextBlockOverflow elements 
if (richTextBlock.HasOverflowContent) 

{ 

// Add the first one 

RichTextBlockOverflow richTextBlockOverflow = new RichTextBlockOverfl ow(); 

richTextBlock.Ove rf1owContentTarget = richTextBlockOverflow; 
flipView.Items.Add(richTextBlockOverflow); 
richTextB1ockOverflow.Measure(containerSize); 
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// Add subsequent ones 

while (richTextBIockOverflow.HasOverflowContent) 

{ 

RichTextBIockOverflow newRichTextBIockOverflow = new RichTextBlockOverfl ow() ; 

richTextBIockOve rf1ow.Ove rf1owContentTarget = newRichTextBIockOverflow; 
richTextBIockOverflow = newRichTextBIockOverflow; 
flipView.Items.Add(richTextBIockOverf 1 ow); 
richTextBIockOve rf1ow.Measure(contai nerSi ze); 

} 



} 


In subsequent firings of the SizeChonged handler, the program could just clear out the 
FlipView and start over again, but I decided to attempt a little more efficiency by adding new 
RichTextBlockOverflow elements if some are needed or removing any that are no longer required: 


Project: SilasMarner I File: MainPage.xaml.es (excerpt) 

async void OnFlipViewSizeChanged (object sender, SizeChangedEventArgs args) 


// Subsequent SizeChanged events 
else 
{ 

// Resize all the items in the FlipView 
foreach (object obj in flipView.Items) 

{ 

(obj as FrameworkElement) .Measure(contai nerSi ze); 

} 

// Generate new RichTextBIockOverflow elements if needed 
while ((f1ipView.Items[f1ipView.Items.Count - 1] 

as RichTextBIockOverfl ow). HasOverf1owContent) 

{ 

RichTextBIockOverflow richTextBIockOverflow = 

f1ipView.Items[f1ipView.Items.Count - 1] as RichTextBIockOverfl ow; 

RichTextBIockOverflow newRichTextBIockOverflow = new RichTextBIockOverfl ow() ; 

richTextBIockOverflow.OverflowContentTarget = newRichTextBIockOverflow; 
richTextBIockOverflow = newRichTextBIockOverflow; 
flipView.Items.Add(richTextBIockOverfl ow); 
richTextBIockOverflow.Measure(args■NewSi ze); 

} 

// Remove superfluous RichTextBIockOverflow elements 
while (!(f1ipView.Items[f1ipView.Items.Count - 2] 

as RichTextBIockOverfl ow). HasOve rflowContent) 

{ 

flipView.Items.RemoveAt(flipVi ew.Items.Count - 1); 



} 
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However, I discovered (as you’ll probably discover) that this logic seems to calculate an insufficient 
number of RichTextBlockOverflow elements. The whole novel is preserved, but some of the licensing 
information toward the end of the file is truncated. I do not know why this happens. 

The SizeChanged processing concludes with initializing the heading text and the Slider and then 
setting the Selectedlndex property of the FlipView to a value based on the fraction Read value: 

Project: SilasMarner I File: MainPage.xaml.es (excerpt) 

async void OnFlipViewSizeChanged (object sender, SizeChangedEventArgs args) 

{ 

// Initialize the header and Slider 
int count = f1ipView.Items.Count; 

pageNumber.Text = "1" ; // probably modified soon 

pageCount.Text = count.ToString(); 
pageSlide r.Minimum = 1; 

pageSlide r.Maxi mum = f1ipView.Items.Count; 

pageSlider.Value = 1; // probably modified soon 

// Go to approximate page 
fractionRead = saveFractionRead; 

f"MpView.Selectedlndex = (i nt)Math .Min(count - 1, fractionRead * count); 

} 


That’s the bulk of the program. The SelectionChongecJ handler for the FlipView changes the 
heading and Slider, and the ValueChanged handler for the Slider changes the Selectedlndex property 
of the FlipView: 

Project: SilasMarner I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

void OnFlipViewSelectionChanged (object sender, SelectionChangedEventArgs args) 

{ 

int pageNum = flipView.Selectedlndex + 1; 
pageNumber.Text = pageNum.ToString(); 
fractionRead = (pageNum - 1.0) / f1ipView.Items.Count; 
pageSlider.Value = pageNum; 

} 

void OnPageSliderVal ueChanged(object sender, RangeBaseValueChangedEventArgs args) 

{ 

flipView.Selectedlndex = Math .Min(f1ipView.Items.Count, (int)args .NewValue) - 1; 

} 

} 


Now that the program is finished, how does it work? 
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Not very well, I think. A few seconds are required every time the SizeChonged handler executes, 
and this is code that cannot be moved to a secondary thread because virtually all of it involves 
user interface objects. Moreover, I’ve experienced some shifting around of the text contents of the 
elements, indicating to me that \'rr\ pushing the envelope of RichTextBlock pagination. 


What these problems imply is that RichTextBlock must be abandoned for performing pagination 
for larger documents. The program itself must take on these tasks, most efficiently based on text 
metric information. If youYe interested in exploring some of the issues — and possible solutions — 
check out a series of articles I wrote for the June through November 2011 issues of MSDN Magazine 
{http://msdn.microsoft.com/en-us/mogozine, and select Issues and Downloads). These articles describe 
code for Windows Phone 7, but the principles are very similar to working with Windows 8. 

In particular, it’s extremely helpful to divide a large document into chapters. In traditional 
typesetting as well as e-book readers, chapters represent points where pagination can begin anew. 
Within a particular chapter, pagination can be performed "on demand" as the need arises for each 
new page. 


Rich Editing with RichEditBox 

Just as there is an enhanced version of TextBlock called RichTextBlock, there is an enhanced version of 
TextBox called...no, it's not called RichTextBox. It's actually RichEditBox. 

If you think of TextBox as the "engine" of the traditional Windows Notepad program, RichEditBox 
might be regarded as the engine of the Windows WordPad program. RichEditBox lets you program¬ 
matically select ranges of text — or (more commonly) allow the user to select ranges of text — and 
apply unique character and paragraph formatting to that selection. RichEditBox also has a built-in file 
loading and saving option, but unfortunately this option supports only the rather quaint Rich Text 
Format (RTF). 

The following discussion just scratches the surface of RichEditBox. You’ll want to begin exploring 
the unique features of this class through the portal of the Document property. This Document 
property is set internally to an object that implements the ITextDocument interface, defined in 
the Windows, ill .Text namespace. That interface supports loading and saving to streams, as well as 
methods to set and obtain default character and paragraph formatting, and to set the formatting for 
ranges of text within the document. 

ITextDocument also supports a Selection property that refers to the area of the document selected 
by the user. This Selection property is of type ITextSelection, which also implements the ITextRonge 
interface. The ITextRange interface supports clipboard copies and pastes, as well as defining 
CharacterFormat and PorographFormot properties, which reference objects that implement the 
ITextChorocterFormat and ITextPorogrophFormat interfaces, respectively. 
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Let’s use RichEditBox to construct a rudimentary rich-text editor called RichTextEditor. This 
program has an application bar at the top to apply character formatting (at the left) and paragraph 
formatting (at the right) and an application bar at the bottom for loading and saving files: 



As soon as you start putting together a program of this sort, you start realizing that the hard part 
is not the RichEditBox programming interface — it's figuring out how to organize the user interface. 

I’ve used eight button styles from StandardStyles.xaml, but StandardStyles.xaml contains styles for 
buttons for font, font color, and font size. If you use those buttons, however, they’ll need to invoke 
popup dialog boxes, and I wanted to avoid that in this program. For that reason, the size and font 
family are implemented as ComboBox controls right on the application bar, and there is no color 
selection. Like I said, I’m only scratching the surface here. 

Here's the XAML file. As you can see, the markup for the RichEditBox is dwarfed by the two AppBar 
definitions: 


Project: RichTextEditor | File: MainPage.xaml (excerpt) 

<Page 

x:Class="Ri chTextEditor.MainPage" 

xml ns="http: //schemas.microsoft.com/winfx/2006/xaml/presentation" 
xml ns : x="http: //schemas.microsoft.com/winfx/2006/xaml" 
xml ns : 1 ocal="usi ng : RichTextEditor" 

xml ns : d="http: //schemas.microsoft.com/expression/blend/2008" 

xml ns : mc="http : //schemas.openxmlformats.org/markup-compatibi1ity/2006" 

mc:Ignorable="d"> 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
〈RichEditBox Name="ri chEditBox" /> 

</Gri d> 
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<Page.TopAppBar> 

<AppBar Opened="OnTopAppBa 「 Opened"> 

<Grid> 

<StackPanel Orientati on="Hori zontal" 

HorizontalA1i gnment="Left"> 

<!-- For CheckBox's, need to comment out BackgroundCheckedGlyph in 
AppBarButtonStyle in StandardStyles.xaml --> 

<CheckBox Name="bol dAppBarCheckBox" 

Style="{Stati〔Resource BoldAppBarButtonStyle}" 
Checked="OnBoldAppBarCheckBoxChecked" 

Unchecked="OnBol dAppBarCheckBoxChecked" /> 

<CheckBox Name="i talicAppBarCheckBox" 

Style="{StaticResource ItalicAppBarButtonStyle}" 
Checked="OnItal icAppBarCheckBoxChecked" 

Unchecked="OnItal icAppBarCheckBoxChecked" /> 


〈CheckBox Name="underl ineAppBarCheckBox" 

Styl e="{StaticResource UnderlineAppBarButtonStyle}" 
Checked="0nUnderl ineAppBarCheckBoxChecked" 
Unchecked="OnUnderl ineAppBarCheckBoxChecked" /> 

<ComboBox Name="fontSi zeComboBox" 

Width="72" 

Margin="12 12 24 36" 

Selecti onChanged="OnFontSi zeComboBoxSelectionChanged"> 
<x:Int32>8</x:Int32> 

<x: Int32>9</x : Int32> 

<x : Int32>10</x : Int32> 

<x : Int32>ll</x : Int32> 

<x : Int32>12</x : Int32> 

<x: Int32>14</x : Int32> 

<x: Int32>16</x : Int32> 

<x : Int32>18</x : Int32> 

<x : Int32>20</x:Int32> 

<x : Int32>22</x:Int32> 

<x: Int32>24</x:Int32> 

<x : Int32>26</x:Int32> 

<x : Int32>28</x : Int32> 

<x : Int32>36</x:Int32> 

<x : Int32>48</x:Int32> 

<x : Int32>72</x:Int32> 

</ComboBox> 


<ComboBox Name="fontFami 1yComboBox" 

Width=”240__ 

Margin="12 12 24 36" 

Selecti onChanged="OnFontFami1 yComboBoxSelectionChanged" /> 

</StackPanel > 

<StackPanel Orientati on="Hori zontal" 

HorizontalA1i gnment="Ri ght"> 

<StackPanel Name="al ignmentPanel" 

Orientati on="Hori zontal"> 

<RadioButton Name="al ignLeftAppBarRadioButton" 

Style="{StaticResource A1ignLeftAppBarButtonStyl e}" 
Checked="OnAli gnAppBarRadioButtonChecked" /> 
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<RadioButton Name="al ignCenterAppBarRadioButton" 

Styl e="{StaticResource A1ignCenterAppBarButtonStyl e} 
Checked="OnAli gnAppBarRadioButtonChecked" /> 


<RadioButton Name="al ignRightAppBarRadioButton" 

Styl e="{StaticResource A1ignRightAppBarButtonStyle} 
Checked="OnAl ignAppBarRadioButtonChecked" /> 

</StackPanel> 

</StackPanel> 

</Gri d> 

</AppBar> 

</Page.TopAppBar> 

<Page.BottomAppBar> 

<AppBar> 

<Grid> 

<StackPanel Orientati on="Hori zontal" 

HorizontalA1i gnment="Left" /> 

<StackPanel Orientati on="Hori zontal" 

HorizontalA1ignment="Ri ght"> 

<Button Style="{Stati cResource OpenFileAppBarButtonStyle}" 

Cli ck="OnOpenAppBarButtonClick" /> 


〈Button Style="{StaticResource SaveAppBarButtonStyle} 
AutomationProperties. Name="Save As" 

Cli ck="OnSaveAsAppBarButtonClick" /> 
</StackPanel > 

</Gri d> 

</AppBar> 

</Page.BottomAppBar> 

</Page> 


A CheckBox is used for the three buttons labeled Bold, Italic, and Underline. These items can 
be either off or on. The ComboBox for the font size is initialized with explicit values. Usually text 
editors provide a facility to enter a custom value, but for reasons of simplicity I eliminated that. The 
ComboBox for the font family is initialized in the code-behind file. The three buttons for the text 
alignment are a group of RodioButton controls. 


Because this project wants to fill up the second ComboBox with a list of fonts installed on the 
system, it includes the DirectXWrapper project from Chapter 15, "Going Native." That ComboBox is 
initialized in the Loaded handler. The Loaded handler also loads a document-in-progress from local 
storage and two settings involving the selection the user last made of that document. That document 
and those settings are saved in the Suspending handler: 

Project: RichTextEditor I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

public MainPage() 

{ 

this. InitializeComponent(); 

Loaded += OnLoaded; 

Application .Current.Suspending += OnAppSuspending; 

} 
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async void OnLoaded(object sender, RoutedEventArgs args) 

{ 

// Get fonts from Di rectXWrapper "library 

Wri teFactory writeFactory = new Wri teFactoryO ; 

WriteFontCol1ection writeFontCol1ection = 

wri teFactory.GetSystemFontCol1ection(); 


int count = writeFontCol1ection.GetFontFami1yCount(); 
stri ng[] fonts = new string [count]; 


for (int i =0; i < count; i++) 

{ 

WriteFontFamily writeFontFamily = 

wri teFontCol 1 ecti on. GetFontFami 1 y ⑴； 


WriteLocalizedStrings writeLocalizedStrings = 

writeFontFamily.GetFami1yNamesC); 


int index; 


if (writeLocalizedStrings.FindLocal eName("en-us" , out index)) 
fonts [i] = writeLocalizedStrings.GetString(index); 

else 

fonts[i] = writeLocalizedStrings.GetString(0); 


Array. So rt<string>(fonts) ; 

fontFamilyComboBox.ItemsSource = fonts; 

// Load current document 

StorageFolder local Folder = Appli cationData.Current. Local Folder; 
try 

StorageFi 1 e storageFile = await local Folder.CreateFileAsync("Ri chTextEditor.rtf" , M 

CreationCol1isionOption. OpenlfExists); 

IRandomAccessStream stream = await StorageFi1e.OpenAsync(Fi 1eAccessMode .Read); 
richEditBox.Document.LoadFromStream (TextSetOptions .FormatRtf, stream); 

} 

catch 

{ 

// Ignore exceptions here 

} 

// Load selection settings 

IPropertySet propertySet = Appli cationData.Current .LocalSettings.Values; 

if (propertySet.Contai nsKeyC'Selecti onStart")) 

richEditBox.Document.Selection.StartPosition = (i nt)propertySet["SelectionStart"] ; 

if (propertySet.Contai nsKeyC’Selecti onEnd")) 

richEditBox.Document.Selection.EndPosition = (i nt) propertySet ["SelectionEnd"] ; 

} 

async void OnAppSuspendi ng(object sender, SuspendingEventArgs args) 

{ 

SuspendingDeferral deferral = args.SuspendingOperation.GetDeferral(); 
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// Save current document 

StorageFolder local Folder = ApplicationData. Current.Local Folder; 


try 

StorageFi1e storageFile = await local Folder.CreateFi1 eAsync("Ri chTextEditor.rtf" , 

CreationCol1isionOption. ReplaceExisting); 

IRandomAccessStream stream = await StorageFi1e.OpenAsync (Fi 1eAccessMode .ReadWrite); 
richEditBox.Document.SaveToStream (TextGetOptions. FormatRtf, stream); 

} 

catch 

{ 

// Ignore exceptions here 

} 

// Save selection settings 

IPropertySet propertySet = ApplicationData .Current.LocalSettings.Values; 
propertySet ["SelectionStart"] = richEditBox.Document.Selection.StartPosition; 
propertySet ["SelectionEnd"] = richEditBox.Document.Selection.EndPosition; 

deferral .CompleteO ; 


The LoodFromStream and SaveToStream methods defined by the ITextDocument interface require 
the FormotRtf enumeration member to load and save RTF files. Otherwise, the methods just load and 
save plain text. 

The Suspending handler saves only the StartPosition and EndPosition properties of the 
ITextSelection object exposed as the Selection property of ITextDocument. If no text is actually 
selected, these values are the same and indicate the current cursor position in the document — the 
current insertion point where typed text is next inserted. 

The program does not save any formatting information because the program doesn’t maintain any 
default formatting that is applicable to new documents or to plain-text files. Those formatting items 
on the application bar are applicable only to a particular selection (or insertion point) of a document. 
All those formatting specifications are internal to the document that RichEditBox maintains. (Of 
course, it’s possible for a program to allow a user to select default formatting for an entire document, 
but that’s another user interface problem.) 

Because the program does not maintain any formatting information, it must initialize all the 
text-formatting items on the top application bar when that application bar appears, which it signals 
with the Opened event. These items are initialized based on the current selection or insertion point 
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in the document. The current settings are available from the CharacterFormat and PorogrophFormot 
properties of the ITextSelection object exposed as the Selection property of ITextDocument: 

Project: RichTextEditor I File: MainPage.xaml.es (excerpt) 

void OnTopAppBarOpened (object sender, object args) 

{ 

// Get the character formatting at the current selection 

ITextCharacterFormat charFormat = richEditBox.Document.Selection.CharacterFormat; 

// Set the CheckBox app bar buttons 

boldAppBarCheckBox.IsChecked = charFormat.Bold == FormatEffect .On; 

italicAppBarCheckBox.IsChecked = charFormat.Ital i c == FormatEffect .On; 

underl ineAppBarCheckBox.IsChecked = charFormat.Underline == UnderlineType. Single; 

// Set the two ComboBox’s 

fontSizeComboBox.Selectedltem = (int) charFormat.Size; 
fontFami1yComboBox.Selectedltem = charFormat.Name; 

// Get the paragraph alignment and set the RadioButton*s 
ParagraphAlignment paragraphAlign = 

richEditBox.Document.Selection.ParagraphFormat.A1 i gnment; 
alignLeftAppBarRadioButton.IsChecked = paragraphAlign == ParagraphAlignment .Left; 
alignCenterAppBarRadioButton.IsChecked = paragraphAlign == ParagraphAlignment .Center; 
alignRightAppBarRadioButton.IsChecked = paragraphAlign == ParagraphAlignment .Right; 

} 

The ITextCharacterFormot object defines Bold, Italic, and Underline properties (as you can see) but 
also supplements those with a familiar Font Style property and a Weight property that is a numeric 
value corresponding to properties of the FontWeights class. 

FormatEffect is an enumeration with values On, Off, Toggle, and Undefined. If the current selection 
contains some italicized and nonitalicized text, the value of the Italic property is FormatEffect 
.Undefined and the corresponding application bar button should probably be set to an indeterminate 
state, but with the standard application bar style, that state looks the same as the unchecked state, so 
I didn’t bother. 

Notice that the font family applicable to the selection is provided by the string Name property of 
the ITextChorocterFormot object. The property has such an innocuous name that it 7 s easy to overlook. 

The Bold, Italic, and Underline buttons are all handled similarly. The Bold, Italic, and Underline 
properties of the / TextCharacterFormat object are set based on the CheckBox state, so these settings 
apply to the current selection or insertion point: 

Project: RichTextEditor I File: MainPage.xaml.es (excerpt) 

void OnBoldAppBarCheckBoxChecked (object sender, RoutedEventArgs args) 

{ ~ 
ri chEditBox.Document.Selection.CharacterFormat.Bold = 

(sender as CheckBox) .IsChecked.Value ? FormatEffect .On : FormatEffect .Off; 

} 
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void OnltalicAppBarCheckBoxChecked(object sender, RoutedEventArgs args) 

{ 

richEditBox.Document.Selection.CharacterFormat.Italic = 

(sender as CheckBox). IsChecked.Value ? FormatEffect .On : FormatEffect .Off; 

} 

void OnUnderlineAppBarCheckBoxChecked(object sender, RoutedEventArgs args) 

{ 

ri chEdi tBox. Document. Sel ection. CharacterFormat. Under"! ine = 

(sender as CheckBox). IsChecked.Value ? UnderlineType. Single : UnderlineType. None; 

} 


The handlers of the two ComboBox controls are just about as simple: 


Project: RichTextEditor I File: MainPage.xaml.es (excerpt) 

void OnFontSizeComboBoxSelectionChanged (object sender, SelectionChangedEventArgs args) 

{ 

ComboBox comboBox = sender as ComboBox; 
if (comboBox.Selectedltem != null) 

{ 

richEditBox.Document.Selection.CharacterFormat.Size = (int) comboBox.Selectedltem; 

} 

} 

void OnFontFami1yComboBoxSelectionChanged (obj ect sender, SelectionChangedEventArgs args) 

{ 

ComboBox comboBox = sender as ComboBox; 
if (comboBox.Selectedltem != null) 

{ 

richEditBox.Document.Selection.CharacterFormat.Name = (stri ng) comboBox.Selectedltem; 

} 

} 

The final formatting item on the application bar applies to paragraphs. The Alignment property 
of the / Tex tPa rograp h Format object is set to one of the Paragraph Alignment enumeration members 
based on the checked RodioButton: 


Project: RichTextEditor I File: MainPage.xaml.es (excerpt) 

void OnAlignAppBarRadioButtonChecked(object sender, RoutedEventArgs args) 

{ 

ParagraphAlignment paragraphAlign = ParagraphAlignment. Undefined; 


if (sender == alignLeftAppBarRadioButton) 

paragraphAlign = ParagraphAlignment ■Left; 

else if (sender == alignCenterAppBarRadioButton) 
paragraphAlign = ParagraphAlignment .Center; 


else if (sender == alignRightAppBarRadioButton) 
paragraphAlign = ParagraphAlignment .Right; 


richEditBox.Document.Selection.ParagraphFormat.Alignment = paragraphAlign; 

} 
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The only remaining code in Main Page handles the Open File and Save As buttons in the bottom 
application bar. The program allows loading and saving files with both .txt and .rtf extensions. This 
code should be fairly clear after the similar code in the Loaded and Suspending handlers that pertain 
to the current document: 


Project: RichTextEditor I File: MainPage.xaml.es (excerpt) 

async void OnOpenAppBarButtonCli ck(object sender, RoutedEventArgs args) 

{ 

Fi1eOpenPicker picker = new Fi1eOpenPi cker() ; 

picker.FileTypeFiIter.Add (" .txt") ; 
picker.FileTypeFi1ter.AddC". rtf") ; 

StorageFile storageFi1e = await picker.PickSingleFi1eAsyncC); 

// If user presses Cancel, result is null 
if (storageFi1e == null) 
return ; 

TextSetOptions textOptions = TextSetOptions .None; 

if (storageFi1e.ContentType != "text/plain") 
textOptions = TextSetOptions. FormatRtf; 

string message = null; 

try 

IRandomAccessStream stream = await storageFi1e.OpenAsync(Fi1 eAccessMode .Read); 
richEditBox.Document.LoadFromStream(textOptions, stream); 

} 

catch (Exception exc) 

{ 

message = exc.Message; 

} 

if (message != null) 

{ 

MessageDialog msgdlg = new MessageDialog ("The file could not be opened. " + 

"Windows reports the following error: 
message, "RichTextEditor"); 

await msgdlg.ShowAsyncC); 

} 

} 

async void OnSaveAsAppBarButtonCli ck(object sender, RoutedEventArgs args) 

{ 

Fi1eSavePicker picker = new Fi1eSavePi cker() ; 

picker.DefaultFi1eExtension = ".rtf" ; 

picker.FileTypeChoices .Add("Ri ch Text Document" , new Li st<string> { ".rtf" }); 
picker.FileTypeChoices. Add("Text Document" , new Li st<string> { ".txt" }); 

StorageFi le storageFi 1e = await picker.PickSaveFileAsyncC); 

// If user presses Cancel, result is null 
if (storageFi1e == null) 
return ; 
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TextGetOptions textOptions = TextGetOptions .None; 

if (storageFile.ContentType != "text/plain") 
textOptions = TextGetOptions .FormatRtf; 

string message = null; 


try 

IRandomAccessStream stream = await storageFi1e.OpenAsync(Fi 1eAccessMode. ReadWrite); 
richEditBox.Document.SaveToStream(textOptions ， stream); 

} 

catch (Exception exc) 

{ 

message = exc.Message; 

} 

if (message != null) 

{ 

MessageDialog msgdlg = new MessageDialog ("The file could not be saved. " + 

"Windows reports the following error: " + 
message ， "RichTextEditor") ; 

await msgdlg.ShowAsyncC); 

} 

} 


The two methods determine whether to use the TextSetOptions. FormatRtf and TextGetOptions 
•FormatRtf f\ags based on the MIME type of the StorageFile returned from the file picker. My 
experience reveals that these file pickers indicate that the MIME type of the selected file is either 
"text/plain" for files with the .txt extensions or "application/msword" for files with .rtf extensions, but I 
was somewhat wary of hard-coding that latter MIME type into the program given that MIME types of 
"text/rtf" and "application/rtf” are also associated with RTF files. 

If the FormatRtf f\ag is not specified, the RichEditBox methods save and load plain-text files. 
However, the SaveToStreom method saves plain text using the Unicode (or UTF-16) encoding, where 
each character in the file occupies two bytes. This encoding is rather uncommon for plain-text files, 
and the files contain no Byte-Order Mark (BOM) at the beginning to indicate the encoding. Windows 
Notepad can load these files — apparently it determines the encoding from an examination of the file 
content — but the PrimitivePad program in Chapter 7, "Asynchronicity,” cannot. It stops reading at the 
first zero encountered in the stream. 


Files saved from PrimitivePad have UTF-8 encoding, but they have no BOM either, so the 
LoadFromStreom method of RichEditBox assumes that the encoding is UTF-16. This means that 
RichTextEditor cannot properly load files saved from PrimitivePad. Each pair of bytes in the file is 
treated as comprising a single Unicode character, and hence pairs of characters of the Latin alphabet 
are displayed mostly as Chinese ideograms. 

Perhaps a better solution to saving and loading plain-text files with RichEditBox is making use of 
the GetText and SetText methods and the regular Windows Runtime file I/O facilities. 
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Your Own Text Input 


Certainly, the TextBox and RichEditBox controls provide the best ways for your program to get text 
input from the computer’s keyboard. But what if you wanted to implement your own text input? 


The UlElement class defines Key Down and Key Up events, and the Control class supplements these 
with On Key Down and On Key Up virtual methods. However, the information is delivered to your 
program in the form of Virtual Key values. VirtuolKey is a large enumeration with members for all the 
possible keys on your keyboard. This information is fine for obtaining activity involving the function 
keys or cursor movement keys, but it’s not so great for alphanumeric input. It’s difficult to derive 
characters from keys in a language-independent and device-independent manner. 

A better event for obtaining character input is called ChorocterReceived, but this event is not 
defined by UlElement. It is instead defined by CoreWindow, which you can easily obtain from the 
Window object associated with your application. 

The GettingCharacterlnput project has a simple demonstration of this technique. The XAML file 
contains a Text Block for displaying the typed characters: 

Project: GettingCharacterlnput | File: MainPage.xaml (excerpt) 

<Page … > 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

<TextBlock Name="txtbl k" 

FontSize="24" 

TextWrappi ng="Wrap" /> 

</Grid> 

</Page> 


The code-behind file attaches a handler for the CharacterReceived event defined by CoreWindow 
and gets all the character input to that window. Characters are unsigned integer values that are cast 
to char values. The only special processing involves the Backspace key: 


Project: GettingCharacterlnput | File: MainPage.xaml.es 

using Windows.UI.Core; 
using Windows.UI.Xaml; 
using Windows.UI.Xaml.Controls; 


namespace GettingCharacterlnput 
{ 

public sealed partial cl ass MainPage : Page 
{ 

public MainPageO 
{ 

thi s .InitializeComponent(); 

Wi ndow.Current.CoreWindow.CharacterReceived += OnCoreWindowCharacterReceived; 

} 

void OnCoreWindowCharacterReceived(CoreWi ndow sender, CharacterReceivedEventArgs args) 
{ 
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} 


// Process Backspace key 

if (args.KeyCode == 8 && txtblk.Text.Length >0) 

{ 

txtblk.Text = txtblk.Text.Substring(0, txtblk.Text.Length - 1); 

} 

// All other keys 
else 
{ 

txtblk.Text += (char)args .KeyCode; 


That Backspace key is the only "editing" facility I’ve provided. The Key Up and Key Down events 
would need to be handled for implementing the use of cursor movement keys to go back and 
forth within the typed text string. You’d probably also want to add a way to select text involving 
the keyboard or pointer. For a more professional implementation, you’d need to draw a cursor and 
independently color text characters and backgrounds to indicate selection. This means you'll probably 
be displaying typed text by using individual TextBlock elements for each character (and I bet TextBox 
and RichEditBox are looking mighty fine about now). 

The big problem with the GettingCharacterlnput project is that it obtains input only from physical 
keyboards. If you need to get input from the touch keyboard that pops up on the screen for TextBox 
and RichEditBox, the process is more involved. Here are the basics: 

The MainPage.xaml file in the BetterCharacterlnput project instantiates a custom control named 
RucJimento ryTextBox: 


Project: BetterCharacterlnput I File: MainPage.xaml (excerpt) 

<Crid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<local : RudimentaryTextBox Background="DarkBl ue" 

Width="320" 

Height="320" /> 

</Crid> 


The RudimentaryTextBox class derives from UserControl, and the visuals consist mostly of a 
TextBlock that will display the typed text: 


Project: BetterCharacterlnput I File: Rudi mentaryTextBox.xaml 


<UserControl 

x:Class=" BetterCharacterlnput.RudimentaryTextBox" 

xml ns="http: //schemas.microsoft.com/winfx/2006/xaml/presentation" 

xml ns : x="http: //schemas.microsoft.com/winfx/2006/xaml"> 

〈Grid Background="DarkBl ue"> 

〈TextBlock Name="txtbl k" 

Foreground=" Yellow" 

FontSi ze="24" 

TextWrappi ng="Wrap" /> 

</Gri d> 

</UserControl > 
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The CharacterReceivecJ event handler in the RudimentaryTextBox code-behind file is identical to the 
one in the previous project, except that the handler is attached only when the control has input focus. 
The class defines a simple Text property for the typed input: 

Project: BetterCharacterlnput I File: RudimentaryTextBox.xaml.es 

using Windows.UI.Core; 

using Windows.UI.Xaml; 

using Windows.UI.Xaml•Automation.Peers; 

using Windows.UI.Xaml.Controls; 

using Windows.UI.Xaml .Input; 

namespace BetterCharacterlnput 

{ 

public sealed partial class RudimentaryTextBox : UserControl 

{ 

public RudimentaryTextBoxO 

{ 

this. InitializeComponent(); 
this .IsTabStop = true; 
this. Text = 

} 

public string Text { set; get; } 

protected override void OnTapped (TappedRoutedEventArgs args) 

{ 

this. Focus (FocusState .Programmatic); 
base .OnTapped(args); 

} 

protected override void OnGotFocus (RoutedEventArgs args) 

{ 

Window. Current.CoreWindow.CharacterReceived += OnCoreWindowCharacterReceived; 
base .OnGotFocus(args); 

} 

protected override void OnLostFocus (RoutedEventArgs args) 

{ 

Window. Current.CoreWindow.CharacterReceived -= OnCoreWindowCharacterReceived; 
base .OnLostFocus(args); 

} 

protected override AutomationPeer OnCreateAutomationPeerC) 

{ 

return new RudimentaryTextBoxPeer(this) ; 

} 

void OnCoreWindowCharacterReceived(CoreWi ndow sender, CharacterReceivedEventArgs args) 

{ 

// Process Backspace key 

if (args.KeyCode == 8 && txtblk.Text.Length >0) 

{ 

txtblk.Text = txtblk.Text.Substring(0, txtblk.Text.Length - 1); 

} 
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// All other keys 
else 


txtblk.Text += (char)args .KeyCode; 

} 

} 



In a real application with multiple custom controls that obtain keyboard input, you might want the 
page rather than the controls themselves to determine when they get keyboard input. 

The only really peculiar part of RudimentoryTextBox is the override of the OnCreoteAutomotionPeer 
method. Automation peers provide programmatic control to the user input functions of controls, 
and they are generally used to implement assistive technologies and application testing. For a con¬ 
trol to be able to invoke the on-screen touch keyboard when it obtains input focus, it must have a 
custom automation peer that derives from FromeworkElementAutomationPeer and implements the 
IValueProvider and ITextProvider interfaces. 

This custom automation peer class must also override the FromeworkElementAutomation Peer 
constructor and the GetPotternCore method. Implementing IValueProvider requires two properties 
and one method. Implementing ITextProvider requires two more properties and four methods, but if 
you’re doing this only to provide your custom control with input from the touch keyboard, you can 
define these methods and properties in very simple ways. 

This example code is not quite as simple as possible, but it’s close: 


Project: BetterCharacterlnput I File: RudimentaryTextBoxPeer.es 

using Windows.Foundation; 

using Windows.UI.Xaml.Automation; 

using Windows.UI.Xaml.Automation■Peers; 

using Windows.UI.Xaml.Automation.Provider; 


namespace BetterCharacterlnput 
{ 

public sealed class RudimentaryTextBoxPeer : FrameworkElementAutomationPeer , 

IValueProvider, ITextProvider 

{ 

RudimentaryTextBox rudimentaryTextBox; 

public RudimentaryTextBoxPeer (RudimentaryTextBox owner) 

: base(owner) 

{ 

this ■rudimentaryTextBox = owner; 
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// Override 

protected override object GetPatternCore(PatternInterface patternlnterface) 

{ 

if (patternlnterface == Patternlnterface .Value || 
patternlnterface == Patternlnterface .Text) 

{ 

return this; 

} 

return base .GetPatternCore(patternlnterface); 

} 

// Required for IValueProvider 
public string Value 
{ 

get { return rudimentaryTextBox.Text; } 

} 

public bool IsReadOnly 

{ 

get { return false; } 

} 

public void SetVal ue(stri ng value) 

{ 

rudimentaryTextBox.Text = value; 

} 

// Required for ITextProvider 

public SupportedTextSelection SupportedTextSelection 

{ 

get { return SupportedTextSelection .None; } 

} 

public ITextRangeProvider DocumentRange 

{ 

get { return null; } 

} 

public ITextRangeProvider RangeFromPoint(Poi nt pt) 

{ 

return null; 

} 

public ITextRangeProvider RangeFromChi1d (IRawEl ementProviderSimple child) 

{ 

return null; 

} 

public ITextRangeProvider [] GetVisibleRanges() 

{ 

return null; 

} 
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public ITextRangeProvider[] GetSelectionO 
{ 

return null; 

} 



You can simplify this even further by returning null from the Value property and removing the 
body from the SetValue property. 

Now when you tap the dark blue RudimentoryTextBox control, the virtual keyboard pops up 
(although getting a screen shot of that momentous event is a whole other story). 
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CHAPTER 17 

Share and Print 


S weep your finger into the right edge of the Windows 8 screen (or press Windows+C), and you'll 
see not only the current date and time pop up but also the column of five icons known as charms: 



The charm in the center navigates straight to the start screen, but the others are intended to provide 
services for your application. Each of them is associated with a "pane" that appears when the user taps 
the charm. When your application is on the screen — except when it’s in the thin Snapped state — it 
can support functionality that is associated with these other four charms. 

This chapter first examines how you can handle the Settings and Share charms before focusing 
more extensively on the Devices charm, which is primarily intended to give your programs access 
to printers. 
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Settings and Popups 


Press the Settings charms for any program shown so far in this book, and you’ll see only one 
item. This Permissions item is provided by Windows and lists the permissions your application has 
requested in the Capabilities section of the Package.appxmanifest file. At run time, your application 
can add items to this Settings list, and the items you add push the Permissions item down to the 
bottom. Commonly, these additional items are intended to provide information about your program 
and might have labels like About, Credits, Terms of Use, or Privacy Statement. Other items can obtain 
input from the user and might be labeled Options or Feedback. 


Usually you implement each of the items you add to the Settings list in a very familiar manner: a 
Popup with a User Control child. By convention, this is positioned on the right edge of the application 
and extends to the entire height of the screen. 

Let me demonstrate by adding a traditional About box to the FingerPaint project. Because I intend 
to submit this program to the Windows Store, I’d like this About box to display a cover of this book 
with a link to buy the book from the website of Microsoft Press’s distributor. I first added a new 
User Control item to the FingerPaint project and called the class AboutBox. Here’s the XAML file: 


Project: FingerPaint | File: AboutBox.xaml (excerpt) 

<UserControl ... Wi dth="400"> 

<UserControl.Transitions> 

<TransitionCol1ecti on> 

<EntranceThemeTransition FromHori zontal0ffset="400" /> 
</TransitionCol1ecti on> 

</UserControl.Transitions 〉 


<Gri d> 

〈Border BorderBrush=" Black" 

BorderThickness="l" 

Background="#404040" 

Margin="0 12" 

Paddi ng="0 24"> 

<StackPanel> 

<StackPanel Orientati on="Hori zontal"> 

<Button Style="{StaticResource PortraitBackButtonStyl e}" 
Foreground=" Black" 

Cli ck="OnBackButtonCl ick" /> 

<TextBlock Text="About" 

Styl e="{StaticResource HeaderTextStyle}" /> 

</StackPanel > 
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〈TextBlock FontSi ze="24" 

FontWei ght="Li ght" 

TextWrappi ng="Wrap" 

Margin= M 24"> 

This program was written by Charles Petzold 
and is just one of many example programs in 
his book 


<Itali oProgramming Windows</Ital i c>, 

6th edition. 

<LineBreak /> 

<LineBreak /> 

You can purchase a copy at many bookstores 
or directly from the 0 1 Reilly website. 
〈 /TextBlock 〉 


<Hyper1inkButton HornzontalAli gnment="Center" 

Navi gatellri ="http: //shop. orei lly. com/product/0790145369079 _ do"> 

<StackPanel > 

<Image Source="Assets/BookCover .gif" 

Stretch="None" /> 

<TextBlock TextAli gnment="Center"> 

<Ital i oProgrammi ng Wi ndowsc/Itali c>, 

6th edition 

</TextB1ock> 

</StackPanel> 

</HyperlinkButton> 

</StackPanel> 

</Border> 

</Grid> 

</UserControl > 

I have given this control a specific width but not a specific height because it will be stretched 
to the height of the window in which it’s displayed. I’ve left a little margin on the top and bottom 
and supplied a transition so that it seems to slide in from the right. It has a Back button with a Click 
handler and a HyperlinkButton with the URL of the catalog page for this book at the O’Reilly website. 
The content of that HyperlinkButton includes an Image element that references a bitmap I added to 
the Assets folder. 


The Click handler for the Back button is pretty sure that the parent of this control is a Popup, so it 
sets the IsOpen property of that Popup to false: 

Project: FingerPaint I File: AboutBox.xaml.es (excerpt) 

void OnBackButtonCli ck(object sender, RoutedEventArgs args) 

{ 

// Dismiss Popup 

Popup popup = this .Parent as Popup; 

if (popup != null) 

popup.IsOpen = false; 

} 

This is one way of dismissing the popup. 
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The impact to the FingerPaint program of implementing this About box is very slight. 
The Main Page constructor obtains a SettingsPane object and attaches a handler for the 
CommondsRequestecJ event: 

Project: FingerPaint I File: MainPage.xaml.es (excerpt) 

public MainPageO 
{ 

// Install a handler for the Settings pane 

SettingsPane settingsPane = Setti ngsPane.GetForCurrentViewC); 
settingsPane.CommandsRequested += OnSettingsPaneCommandsRequested; 

} 


SettingsPane and related classes and enumeration are the occupants of the Windows 
.UI.ApplicotionSettings namespace. Conceptually, the SettingsPane object refers to the pane that 
Windows displays when the user presses the Settings charm. That’s why you obtain the SettingsPane 
object rather than creating it. When it displays itself, the pane requests the application to add 
additional items. That's what the CommondsRequested handler does. 

Hooking into the other charms is similar. SettingsPane also has a Show method that displays the 
settings pane programmatically, but for most purposes you’ll just want to install a handler for the 
CommondsRequested event. You don't need to retain the SettingsPane object, so you can combine 
the two statements in the MainPage constructor into one: 

SettingsPane. GetForCurrentView().CommandsRequested += OnSettingsPaneCommandsRequested; 

The CommandsRequested event is fired when your program is active and the user presses the 
Settings charm. This is your opportunity to add additional commands to the Settings pane. Because 
you're doing this every time the Settings charm is pressed, you can tailor these additional commands 
for the current application state. 

FingerPaint processes this CommondsRequested event by adding one SettingsCommond object to 
the list: 

Project: FingerPaint | File: MainPage.xaml.es (excerpt) 

void OnSettingsPaneCommandsRequested(Setti ngsPane sender, 

SettingsPaneCommandsRequestedEventArgs args) 

{ 

SettingsCommand aboutCommand = new Setti ngsCommand(0 , "About" , OnAboutlnvoked); 
args■Request.ApplicationCommands.Add(aboutCommand); 

} 


This command has an ID (which I’ve set to 0 because I’m not using it), a text label, and a 
method that’s called when the user selects that command. After the program returns from the 
CommondsRequested handler, the pane is displayed with that new "About" item. 
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Here’s the method that processes that command: 


Project: FingerPaint I File: MainPage.xaml.es (excerpt) 

void OnAboutlnvokedCIUICommand command) 

{ 

AboutBox aboutBox = new AboutBoxO; 

aboutBox.Height = this .Actual Height; 

Popup popup = new Popup 

{ 

IsLightDismissEnabled = true , 

Child = aboutBox, 

IsOpen = true, 

HorizontalOffset = this .ActualWidth - aboutBox.Width 

}； 

} 


Because the Popup appears at a fixed location on the right side of the page, the code to set the 
Height of the AboutBox and the HorizontalOffset of the Popup is very simple, and here it is: 



® About 


This program was written by 
Charles Petzold and is just one of 
many example programs in his 
book Programming Windows, 6th 
edition. 

You can purchase a copy at many 
bookstores or directly from the 
O'Reilly website. 


Programming 

Windows 

Sixth Edition 

Writing Windows B Apps 
With C* and XAML 


ChadMf 

ndows, 6 



The IsLightDismissEnoblecJ property setting ensures that the Popup is dismissed when the user 
presses anywhere outside the Popup, and the Back button within AboutBox provides dismissal as well. 
If the user presses the Hyperlink button, the Popup is dismissed as Internet Explorer is launched. 
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Sharing Through the Clipboard 


Sharing data through the Share charm involves classes in the Windows.ApplicotionModel.DataTronsfer 
and Windows.ApplicotionModel.DotoTronsfer.ShoreTorget namespaces. That first namespace also 
includes a very traditional mechanism for transferring data among Windows applications: the clipboard. 

I want to first add clipboard support to FingerPaint before tackling the Share charm. Adding this 
support to a program that works with bitmaps is potentially complex. You might want to implement 
a selection API that allows the user to carve out a rectangular area of the painting and copy that to 
the clipboard. You might also want to implement a paste API that allows an incoming bitmap to be 
positioned somewhere on the current image. 

But I’m going to take the simple route: The Copy command will copy the entire artwork to the 
clipboard, and the Paste command will treat the incoming bitmap as a new image, just as if it had 
been loaded from a file but without a filename. 

The first job is to add Copy and Paste buttons to the application bar: 


Project: FingerPaint I File: MainPage.xaml (excerpt) 

<Page.BottomAppBar> 

<AppBar> 

<Gri d> 

<StackPanel Orientati on="Hori zontal" 

HornzontalA1i gnment="Left"> 

〈Button Styl e="{StaticResource CopyAppBarButtonStyl e}" 

Cli ck="OnCopyAppBarButtonCl i ck" /> 

〈Button Name="pasteAppBarButton" 

Styl e="{StaticResource PasteAppBarButtonStyle}" 

Cli ck="OnPasteAppBarButtonClick" /> 

</StackPanel> 

</Gri d> 

</AppBar> 

</Page.BottomAppBar> 

The Paste button needs a name because it must be enabled and disabled from code based on the 
presence of actual bitmap data in the clipboard. 


I decided to implement all the data-sharing code in another partial class implementation of 
Main Page with a filename of MainPage.Share.es. The Main Page constructor calls a method in that 
class: 

Project: FingerPaint I File: MainPage.xaml.es (excerpt) 

public MainPageO 

{ 

// Cal 1 a method in MainPage.Share.es 
InitializeSharing(); 

} 
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In part, that method checks if the Paste button should be initially enabled and then sets an event 
handler that’s called when the content of the clipboard changes: 

Project: FingerPaint I File: MainPage.Share.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

void InitializeSharing() 

{ 

// Initialize the Paste button and provide for updates 
CheckForPasteEnable(); 

Clipboard .ContentChanged += OnClipboardContentChanged; 

} 

void OnClipboardContentChanged(object sender, object args) 

{ 

CheckForPasteEnable(); 

} 

void CheckForPasteEnable() 

{ 

pasteAppBarButton.IsEnabled = CheckClipboardForBitmap(); 

} 

bool CheckClipboardForBitmap() 

{ 

DataPackageView dataView = Clipboard. GetContentO; 
return dataView.Contains (StandardDataFormats .Bitmap); 

} 


Clipboard is a small static class with only four methods and one event. The two most crucial 
methods are GetContent and SetContent. GetContent returns a Data Package Vie w object that provides 
a convenient way to check the current contents of the clipboard to determine whether a bitmap is 
present. 

SetContent requires a DataPackoge object, which has a bunch of methods to put various forms of 
data into the clipboard, including one named Set Bitmap. The handler for the clipboard Copy button 
creates a DotoPockoge and sets the operation to Move, meaning that the program is not interested in 
any further involvement with the bitmap that it's putting into the clipboard: 


Project: FingerPaint I File: MainPage.Share.es (excerpt) 

async void OnCopyAppBarButtonCli ck(object sender, RoutedEventArgs args) 

{ 

DataPackage dataPackage = new DataPackage 

{ 

RequestedOperation = DataPackageOperation. Move, 

}； 

dataPackage.SetBitmap (await GetBitmapStream(bitmap)); 


} 


Clipboard .SetContent(dataPackage); 
this. BottomAppBar.IsOpen = false; 
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However, that SetBitmop method does not want something as mundane as a BitmopSource. 

Instead, it wants a RandomAccessStreamReference that references an encoded bitmap image. You can 
create a RondomAccessStreomReference from an InMemoryRandomAccessStreom. That's the job of the 
GetBitmopStreom method referenced in the call to SetBitmop. 

Notice that the argument to the GetBitmapStreom call is the WriteableBitmap stored as a field in 
Main Page. I made the GetBitmapStreom somewhat generalized in that it creates its own pixels array 
from that argument, but there’s no reason why it couldn’t access the existing pixels array also stored 
as a field in MainPage: 


Project: FingerPaint I File: MainPage.Share.es (excerpt) 

async Task<RandomAccessStreamReference> GetBitmapStream(Wri teableBitmap bitmap) 

{ 

// Get a pixels array for this bitmap 

byte[] pixels = new byte [4 * bitmap.PixelWidth * bitmap.Pixel Height]; 

Stream stream = bi tmap. Pixel Buffer .AsStreamO ; 
await stream.ReadAsyncCpixels, 0 ， pixels■Length); 

// Create a BitmapEncoder associated with a memory stream 
InMemoryRandomAccessStream memoryStream = new InMemoryRandomAccessStreamO ; 

BitmapEncoder encoder = await BitmapEncoder. CreateAsync(Bi tmapEncoder. PngEncoderld, 

memoryStream); 

// Set the pixels into that encoder 

encoder.SetPixelData(Bi tmapPixelFormat. Bgra8, BitmapAlphaMode. Premultipiied, 

(uint) bitmap.PixelWidth, (uint) bitmap.PixelHeight ， 96 ， 96 ， pixels); 
await encoder.FlushAsyncC); 

// Return a RandomAccessStreamReference 

return RandomAccessStreamReference .CreateFromStream(memoryStream); 


The Paste logic is a bit more complex, and not only because the button must be enabled based 
on the existence of bitmap content in the clipboard. If the current painting hasn’t been saved and the 
user presses the Paste button, the program should request whether that artwork should be saved or 
abandoned, just as if the user had elected to load a new file. 

That means that the handler for the Paste button should call the ChecklfOkToTroshFile method 
in MainPage.File.es, passing to it a method that should be executed if the Paste operation should 
proceed. It was unclear to me how much processing of the incoming bitmap I should do before 
calling ChecklfOkToTroshFile. I was worried that the user might elect to save the existing picture and 
somehow the contents of the clipboard would change during that time. I avoid that problem by 
getting the pixels array right away. However, the code doesn't create the WriteableBitmap just yet. 
Delaying that job required that several items associated with the new bitmap be saved as fields: 


Project: FingerPaint I File: MainPage.Share.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

int pastedPixelWidth ， pastedPixelHeight; 
byte[] pastedPixels; 
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async void OnPasteAppBarButtonCli ck(object sender, RoutedEventArgs args) 

{ 

// Temporarily disable the Paste button 
Button button = sender as Button ; 
button.IsEnabled = false; 

// Get the Clipboard contents and check for a bitmap 
DataPackageView dataView = Clipboard .GetContentC); 

if (dataView.Contai ns(StandardDataFormats. Bitmap)) 

{ 

// Get the stream reference and a stream 

RandomAccessStreamReference streamRef = await dataView.GetBitmapAsync(); 
IRandomAccessStreamWithContentType stream = await streamRef.OpenReadAsyncO; 

// Create a BitmapDecoder for reading the bitmap 

BitmapDecoder decoder = await BitmapDecoder .CreateAsync(stream); 

BitmapFrame bitmapFrame = await decoder.GetFrameAsync(O); 

PixelDataProvider pixelProvider = 

await bitmapFrame.GetPixelDataAsync(Bi tmapPixelFormat. Bgra8, 

BitmapAlphaMode. Premultipiied, 
new BitmapTransformO , 

ExifOri entationMode. RespectExifOrientation, 
ColorManagementMode .ColorManageToSRgb); 

// Save information sufficient for creating WriteableBitmap 
pastedPixelWidth = (int)bi tmapFrame.PixelWidth; 
pastedPixelHeight = (int)bi tmapFrame.Pixel Height; 
pastedPixels = pixelProvider.DetachPixelData(); 

// Check if it's OK to replace the current painting 
await ChecklfOkToTrashFi1e(FinishPasteBitmapAndPixelArray); 


// Re-enable the button and close the app bar 

button.IsEnabled = true; 

this .BottomAppBar.IsOpen = false; 

} 

async Task Fi ni shPasteBi tmapAndPi xelArrayO 

{ 

bi tmap = new WriteableBi tmap(pastedPixelWidth, pastedPi xelHei ght); 
pixels = pastedPixels; 

// Transfer pixels to bitmap, among other chores 
await InitializeBitmapO; 

// Set AppSettings properties for new image 
appSettings.LoadedFi1ePath = null; 
appSettings.LoadedFi1ename = null; 
appSettings.IsImageModifi ed = false; 

} 


CHAPTER 17 Share and Print 


901 


There’s just one more job that needs to be done to implement this clipboard support: Many users 
are familiar with using Ctrl+C and Ctrl+V for performing Copy and Paste operations, so I added that 
support to MainPage.Share.es as well, piggy-backing off the existing button handlers. 


Project: FingerPaint I File: MainPage.Share.es (excerpt) 

public sealed partial class MainPage : Page 


void InitializeSharing() 

{ 

// Watch for accelerator keys for Copy and Paste 

Window. Current.CoreWindow.Dispatcher.AcceleratorKeyActivated += 

OnAcceleratorKeyActivated; 

} 


void OnAcceleratorKeyActivated(CoreDi spatcher sender, AcceleratorKeyEventArgs args) 

{ 

if ((args.EventType == CoreAcceleratorKeyEventType .SystemKeyDown || 
args.EventType == CoreAcceleratorKeyEventType .KeyDown) && 

(args.VirtualKey == VirtualKey .C || args.VirtualKey == VirtualKey .V)) 

{ 

CoreWindow window = Window. Current.CoreWindow; 

CoreVirtualKeyStates down = CoreVirtualKeyStates. Down; 

// Only want case where Ctrl is down 

if ((window.GetKeyState(Vi rtualKey .Shi ft) & down) == down || 

(window.GetKeyState(Vi rtualKey .Control) & down) != down || 

(window.GetKeyState(Vi rtualKey .Menu) & down) == down) 

{ 

return ; 

} 

if (args.VirtualKey == VirtualKey .C) 

{ 

OnCopyAppBarButtonCli ck(null , null) ; 

} 

else if (args.VirtualKey == VirtualKey .V) 

{ 

OnPasteAppBarButtonClick(pasteAppBarButton, null); 
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The Share Charm 


A program can use the Share charm in two ways. What I’ll be showing you here is how a program 
can provide data to other applications. It is rather more difficult for an application to function as a 
target for data from other applications. This second job requires that an application assert itself as a 
Share Target in the Declarations section of Package.appxmanifest, be activated in a unique state, and 
provide a special user interface for that purpose. 

A program can be a Share provider by setting an event handler for a DataTransferMonoger 
instance, and a program that provides a bitmap to another application does so with the same 
RandomAccessStreamReference used to copy a bitmap to the clipboard. With the GetBitmapStream 
method already defined in MainPage.Share.es, the additional code to support the Share charm is 
nearly trivial: 


Project: FingerPaint I File: MainPage.Share.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

void InitializeSharing() 

{ 

// Hook into the Share pane for providing data 

DataT ransferManager .GetForCurrentView().DataRequested += OnDataTransferDataRequested; 

} 

async void OnDataTransferDataRequested(DataT ransferManager sender, 

DataRequestedEventArgs args) 

{ 

DataRequestDeferral deferral = args.Request.GetDeferral(); 

// Get a stream reference and hand it over 

RandomAccessStreamReference reference = await GetBitmapStream(bitmap); 

args■Request.Data.SetBitmap(reference); 

args.Request.Data.Properties.Title = "Finger Paint"; 

args.Request.Data.Properties.Description = "Share this painting with another app" ; 
deferral.Complete(); 

} 

} 

Now when the user selects the Share charm when FingerPaint is running, instead of the pane 
derisively reporting that "This app can’t share,” it says "Finger Paint” and "Share this painting with 
another app." Obviously, the DotoRequested event handler has already been called and Windows has 
the RandomAccessStreamReference, so what follows in the Share pane is a list of those applications 
that can accept bitmap data. There is no further interaction required of the program because it has 
already provided the bitmap. 
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Basic Printing 


For any program shown so far in this book, if you invoke the charms and press the Devices charm, 
you'll get a Devices pane that won’t mention anything about printers. Your application needs to 
register with Windows 8 that it is capable of printing. 

Three namespaces play a role in printing: 

■ The Windows.Ul.Xoml.Printing namespace has the PrintDocument class and support for its 
events. As the name suggests, a PrintDocument represents something that the user of your 
program wishes to print. 

■ The Windows.Graphics.Printing namespace has PrintMcmager, which is the interface to the 
pane that Windows 8 provides that lists printers and printer options; and the PrintTask, 
PrintToskRequest, and PrintTaskOptions classes. A print "task" is the same thing as a print 
"job" — a particular use of the printer to print a particular document. 

■ The Windows.Graphics.Printing.OptionDetails namespace contains classes you’ll use for 
customizing printing options. 

Much of the printer API involves overhead rather than the process of actually defining text and 
graphics for the printer page. Indeed, a Windows 8 application prints on a printer page in the same 
way that it draws on the screen: with a visual tree of instances of classes that derive from UlElement. 
Generally, the root element is a Border ora Panel of some sort with children. This visual tree can be 
defined in XAML but is probably more often constructed in code. 

When defining elements to be displayed on the screen, one useful guideline is to treat the video 
display as if it has a resolution of 96 pixels per inch. For the printer, you do the same except that the 
equivalence is exact. Regardless of the actual resolution of the printer, you always treat it as a 96 DPI 
device. 

To persuade Windows 8 to list printers when the user taps the Devices charm, the first task is to set 
an event handler: 

PrintManager printManager = Pri ntManager.GetForCurrentView(); 

printManager.PrintTaskRequested += OnPrintManagerPrintTaskRequested; 

Those two lines can be combined into one: 

Pri ntManager.GetForCurrentView().PrintTaskRequested += OnPrintManagerPrintTaskRequested; 

The static GetForCurrentView method obtains a PrintManager instance that is associated with 
your program’s window. By setting a handler for the PrintTaskRequested event, your program is 
announcing its availability for printing. The handler looks like this: 


void OnPrintManagerPrintTaskRequested(Pri ntManager sender, PrintTaskRequestedEventArgs args) 
{ 

} 
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That handler is called when the user clicks the Devices charm (or presses Windows+K), but (as you’ll 
see shortly) it needs to call another method with a callback function in order for Windows to display 
the list of printers. 

This PrintToskRequested handler should be attached only when the application is in a position to 
actually print something. If the application requires some preliminary information from the user or 
needs to load a document before it can legitimately print, the handler should not be attached to the 
PrintToskRequested event. The handler should be detached when the program finds itself again in a 
position where it doesn’t make any sense to print anything: 

Pri ntManager.GetForCurrentView().PrintTaskRequested -= OnPrintManagerPrintTaskRequested; 

In the sample programs in this chapter, I mostly attach and detach this event handler in the 
OnNavigatedTo and OnNavigatedFrom overrides as a symbolic representation of this process. 

The handler for the PrintToskRequested event is one of five callback methods and event handlers 
required of a program that performs simple printing. All five are required. Moreover, before the 
PrintToskRequested event is even fired, your program needs to have prepared itself for printing by 
creating a PrintDocument object and attaching three event handlers to it. 

So, let’s look at a complete program that prints a one-page document consisting of a single 
TextBlock announcing "Hello, Printer!” The XAML file in the HelloPrinter project doesn’t play a role in 
the program logic and simply informs a new user how to print something: 


Project: HelloPrinter I File: MainPage.xaml (excerpt) 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

〈TextBlock FontSi ze="48" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Center" 

TextAli gnment="Center"> 

Hello, Printer! 

<LineBreak /> 

<Run FontSi ze="24"> 

(Invoke charms, select Devices and a printer) 

</Run> 

</TextBlock> 

</Grid> 

The code-behind file defines three fields, one of which is the TextBlock that the program prints: 

Project: HelloPrinter I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

PrintDocument printDocument; 

IPrintDocumentSource printDocumentSource; 
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// UIElement to print 
TextBlock txtblk = new TextBlock 
{ 

Text = "Hello, Printer !”， 

FontFamily = new FontFamily ("Times New Roman") , 
FontSize = 48, 

Foreground = new SolidColorBrush(Colors .B1ack) 

}； 

} 


The PrintDocument object represents what your application prints. Generally, a program will create 
just one PrintDocument object and use it for every print task. In some cases, it might make sense for 
a program to maintain multiple PrintDocument objects — perhaps one to print the whole document, 
another to print a document outline, and a third to print thumbnails — but you shouldn’t be creating 
new PrintDocument objects for every print task. (As you’ll see, by the time a print task is requested, 
it’s actually too late to create the PrintDocumentl) If it’s convenient, you can derive a class from 
PrintDocument to encapsulate some printing logic, but there’s nothing in PrintDocument to override. 

For a program that deals with a single type of document, you'll probably define the PrintDocument 
and IPrintDocumentSource as fields as I’ve done and create the PrintDocument object during program 
initialization: 


Project: HelloPrinter I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 
{ 

public MainPageC) 

{ 

this .InitializeComponent(); 

// Create PrintDocument and attach handlers 

PrintDocument = new PrintDocument() ; 

printDocumentSource = printDocument.DocumentSource; 

printDocument.Paginate += OnPrintDocumentPaginate; 

printDocument.GetPreviewPage += OnPrintDocumentGetPreviewPage; 

printDocument.AddPages += OnPrintDocumentAddPages; 



The second field — the object of type I PrintDocumentSource — is obtained from the PrintDocument 
object. In addition, three events defined by PrintDocument require handlers. These event handlers 
are responsible for supplying a page count as well as the actual pages for print preview and actual 
printing. 

The HelloPrinter program attaches a handler for the PrintToskRequested event of the PrintManager 
during OnNavigatedTo and detaches it during OnNaviga ted From, using two statements in the first 
case and one statement in the second just for a little variety. 
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Project: HelloPrinter I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 
{ 

protected override void OnNavigatedTo (NavigationEventArgs args) 

{ 

// Attach PrintManager handler 

PrintManager printManager = PrintManager .GetForCurrentView(); 

printManager.PrintTaskRequested += OnPrintManagerPrintTaskRequested; 

base.OnNavigatedTo(args); 

} 

protected override void OnNavigatedFrom(Navi gationEventArgs e) 

{ 

// Detach PrintManager handler 

PrintManager .GetForCurrentView().PrintTaskRequested -= OnPrintManagerPrintTaskRequested; 
base.OnNavigatedFrom(e); 

} 

} 

In a real-life program, you’ll be attaching this handler when your program is capable of printing, and 
detaching it when it has nothing to print. 

When your program has this handler attached and the user sweeps a finger on the right side of the 
screen and then selects Devices, the PrintTaskRequestecJ event handler is called. Here's the standard 
way to respond to that event: 

Project: HelloPrinter I File: MainPage.xaml.es (excerpt) 

void OnPrintManagerPrintTaskRequested(Pri ntManager sender, PrintTaskRequestedEventArgs args) 

{ 

args■Request.CreatePri ntTask("Hello Printer" , OnPrintTaskSourceRequested); 

} 

The event arguments to the PrintTaskRequested event include a property of type Request, and the 
program usually responds by calling the CreatePrintTask method of that Request object, passing to it 
the name of the printer task — this could be the name of the application or the name of a document 
being printed by the application — and a callback function. The CreotePrintTosk method returns a 
PrintTask object, but it’s not usually necessary to retain that object here. 
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Windows 8 then displays a list of printers. Here’s what comes up on my screen (your mileage 
may vary): 


Devices 

HelloPrinter 

HP Deskjet D4100 series on G... 


Hello, Printer! 

(Invoke charms, select Devices and a printer) 


«!■ 

i 


Send To OneNote 2010 


Microsoft XPS Document Writer 


Second screen 


The only real printer here is the first one on the list. The second two items cause printing output to be 
saved in files. The last item isn’t a printer at all and instead configures the second monitor attached to 
my tablet. 

The callback I’ve named OnPrintTaskSourceRequested is called when the user selects one of the 
printers on the list. In the simplest case, the handler can respond by calling SetSource on the event 
arguments, passing to it the IPrintDocumentSource object obtained earlier from the PrintDocument 
object: 


Project: HelloPrinter I File: MainPage.xaml.es (excerpt) 

void OnPrintTaskSourceRequested(Pri ntTaskSourceRequestedArgs args) 
{ 

args.SetSource(printDocumentSource); 

} 
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When this method returns control back to Windows, a printer-specific pane is displayed: 


Hello, Pr 

(Invoke charms, select De ， 


©HP Deskjet D4100 series on GUESTROOM... 


Hello, Printer! 


Copies 



More settings 




The name of the printer at the top of the screen might look a little odd. This particular printer isn’t 
actually attached to the tablet on which I’m working but is instead on a computer in the guest room 
of the house where I’m writing this chapter, and what you’re seeing there is part of that computer’s 
name. 

Over at the right is a box to specify the number of copies and a drop-down to select Portrait or 
Landscape. These are standard settings for printers. (For the "Send To OneNote 2010" and "Microsoft 
XPS Document Writer” options, only the Orientation option is shown in this area.) Pressing "More 
settings" makes available an option to select page size as well as some printer-specific options. 

At the left of this pane is a preview of the page to be printed. If the document has more than 
one page, you can select the page to view by using the little box below it. But the page preview is a 
FlipView control, and it’s easiest just to sweep it from side to side. 

The total number of pages comes from the handler for the Paginate event, which is one of the 
three events defined by PrintDocument. Handlers for all three of these events were attached in the 
Main Page constructor. In HelloPrinter the Paginate handler is implemented simply like this: 

Project: HelloPrinter I File: MainPage.xaml.es (excerpt) 

void OnPrintDocumentPagi nate(object sender, PaginateEventArgs args) 

{ 

pri ntDocument.SetPrevi ewPageCount(1 ， PreviewPageCountType .Final); 

} 

This Paginate handler is the application’s opportunity to prepare all the pages for printing and 
then call a PrintDocument method indicating the number of pages available and whether this is a 
preliminary or final count. (If it’s not possible or convenient to do all that work in one shot, things get 
a little more complex.) 
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The preview of the print page is supplied by the handler for the GetPreviewPage event also defined 
by PrintDocument and also set earlier in the MoinPage constructor: 

Project: HelloPrinter I File: MainPage.xaml.es (excerpt) 

void OnPrintDocumentGetPrevi ewPage(object sender, GetPreviewPageEventArgs args) 

{ 一 
printDocument.SetPreviewPage(args.PageNumber, txtblk); 

} 

The PageNumber property of the event arguments is one-based and can range from 1 to the number 
specified in the SetPreviewPageCount call. For this particular program, it will always equal 1. The pro¬ 
gram responds to this event by calling the SetPreviewPoge method of PrintDocument, passing to it the 
page number and the TextBlock that I defined as a field. That’s what’s displayed in the print preview. 

When the Print button is pressed, the final event handler is called: 


Project: HelloPrinter I File: MainPage.xaml.es (excerpt) 

void OnPrintDocumentAddPages (object sender, AddPagesEventArgs args) 

{ 

printDocument.AddPage(txtblk); 
printDocument.AddPagesComplete(); 

} 

The handler for the AddPages event is responsible for calling Add Page for every page in the 
document. In the usual case, these are the same objects passed to the SetPreviewPoge method, 
but you do have an opportunity to make them different if you wish. It concludes with a call to 
AddPogesComplete. The printing pane disappears, and (with any luck) you'll hear the familiar sound of 
a printer kicking into action. 

Watch out! The Paginate handler can be called more than once, particularly if the user starts 
playing around with various printer options. If your program is actually performing a lot of work to 
paginate the document, you’ll probably want to avoid repeating it when the actual layout of the page 
doesn’t change. In a real-life program generally you’ll assemble all your pages in a List object during 
the Paginate handler and then deliver them up in the GetPreviewPage and Add Pages handlers. 

The TextBlock that HelloPrinter prints is given a FontSize of 48. That TextBlock might appear to 
have somewhat different sizes when it’s seen on video displays of different sizes and resolutions. But 
when it’s printed, that FontSize of 48 is an exact measurement and means 48/96 inch, which is half an 
inch or 36 points. 

You’ll notice I specified that the Foreground property of that printable TextBlock is black. Because 
this program uses a dark theme, the default Foreground property is white, and without an explicit 
Foreground setting, this TextBlock gets the default and would be invisible on white paper. This is the 
type of thing that can have you baffled for days! When experimenting with printer code, it might 
be helpful to get in the habit of using colors such as Red and Blue so that there’s less of a chance of 
printing white text. 

As you look over the code in HelloPrinter, you might think you see a couple ways to simplify it. For 
example, you might think you don’t need to create a PrintDocument initially and save it as a field. You 
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could simply create it in the OnPrintTaskSourceRequested method, set the three event handlers, and 
extract the IPrintDocumentSource object. The various PrintDocument event handlers can get access to 
the PrintDocument from the sender argument. 

But this will not work. The PrintDocument needs to be created and accessed in the user-interface 
thread, and the PrintToskRequested handler and the callback IVe named OnPrintTaskSourceRequested 
do not run in the user-interface thread. If you wait until the PrintToskRequested event is fired to create 
the PrintDocument, it's too late. 

Printable and Unprintable Margins 

Even with the caution of printing the TextBlock in black, it's not printed correctly on my printer, and 
it’s probably not printed correctly on your printer either. The TextBlock is aligned smack against the 
upper-left corner of the page, and most printing mechanisms simply can’t reach to the edge of the 
paper, which means that part of the text is sheared off. 

If you try to solve this problem by setting the HorizontolAlignment and Vertical A lignmen t 
properties of the TextBlock to Center, you’ll discover these properties don’t work in this case. The 
alignment values are relative to a parent element, and this TextBlock has no parent because it’s 
the top-level element on the printer page. Margin won’t work either for the same reason. Setting 
the Podding property on the TextBlock will work, however, because that's something the TextBlock 
handles itself. 

A much better general-purpose solution is for every printer page to be a visual tree that begins 
with a top-level Border object. When printed, this Border will occupy the entire size of the paper, but 
the Border can include a nonzero Padding property that effectively provides a margin for the entire 
page. 

Both Pog in ate Event A rgs and AddPogesEventArgs include a property named PrintToskOptions of 
type PrintToskOptions. Most of the properties of this object correspond to the printer properties that 
the user can set manually. These properties have names like Collation, NumberOfCopies, Orientation, 
and PrintQuality. A program can access these properties to customize printing, but this is generally 
not necessary. Ill show you later in this chapter how a program can initialize these properties and add 
some custom options. 

PrintToskOptions also has a method named GetPageDescription. The argument is a zero-based 
page number under the assumption that each page can be a different size. The PrintPageDescription 
structure returned from this method has DpiX and DpiY properties, which report the actual resolution 
of the printer (very often values like 600 or 1200) and a PogeSize of type Size in units of 1/96 inch. 

For American standard letter size 8 V 2 x 11 〃 paper in portrait mode, the PogeSize properties are 816 
and 1056. 

The PrintPageDescription structure also includes an ImageableRect property of type Rect that 
indicates the rectangular area of the page where the printer can actually print. For letter size paper 
on my printer, this rectangle has an upper-left corner at (12.48, 11.35748) and a size of (791.04, 
988.1575), all in units of 1/96 inch. Compare this with the PogeSize of 816 by 1056. Perform a few 
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subtractions and you’ll conclude that the printer can’t print on the 12.48 units on the left and right 
edges, 11.35748 units on the top, and 56.48502 units (over Vi inch) on the bottom. In landscape 
mode, both PageSize and ImageableRect reflect the particular orientation of the page. 


Let’s examine how accurate these numbers are. The PrintPrintableArea program announces the 
name of itself in its XAML file: 


Project: PrintPrintableArea | File: MainPage.xaml (excerpt) 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<TextBlock Text="Pri nt Printable Area" 

FontSize="24" 

Hori zontalAl i gnment="Center" 

VerticalA1i gnment="Center" /> 

</Crid> 


The code-behind file is structured very much like HelloPrinter except that the element to be 
printed by the program is rather more extensive, consisting of a Border with a red background, a 
nested Border with a white background and a black outline, and a centered TextBlock. 

You’ll notice also that instead of a separate callback method passed to the CreatePrintTask method, 
I’ve defined it as an anonymous lambda function. This is a common practice, but I’ve become less 
enamored of it for more complex printing logic: 


Project: PrintPrintableArea | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

PrintDocument printDocument; 

IPrintDocumentSource printDocumentSource; 


// Element to print 
Border border = new Border 
{ 

Background = new SolidColorBrush(Colors .Red), 

Child = new Border 

{ 

Background = new SolidColorBrush (Col ors .White), 
BorderBrush = new SolidColorBrush (Col ors. Black), 
BorderThickness = new Thi ckness(l) , 

Child = new TextBlock 

{ 

Text = "Print Printable Area" , 

FontFamily = new FontFamily ("Times New Roman") , 
FontSize = 24 ， 

Foreground = new SolidColorBrush (Col ors. Black), 
HorizontalAlignment = HorizontalAlignment. Center, 
VerticalAlignment = VerticalA1ignment .Center 

} 

} 

}； 


public MainPage() 

{ 

this. InitializeComponent(); 
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// Create PrintDocument and attach handlers 

printDocument = new PrintDocument() ; 

printDocumentSource = printDocument.DocumentSource; 

printDocument.Paginate += OnPrintDocumentPaginate; 

printDocument.GetPreviewPage += OnPrintDocumentGetPreviewPage; 

printDocument.AddPages += OnPrintDocumentAddPages; 

} 

protected override void OnNavigatedTo(Navi gationEventArgs args) 

{ 

// Attach PrintManager handler 

PrintManager. GetForCurrentView().PrintTaskRequested += OnPrintManagerPrintTaskRequested; 
base. OnNavigatedTo(args); 

} 

protected override void OnNavigatedFrom(Navi gationEventArgs e) 

{ 

// Detach PrintManager handler 

PrintManager. GetForCurrentView().PrintTaskRequested -= OnPrintManagerPrintTaskRequested; 
base. OnNavigatedFrom(e); 

} 


void OnPrintManagerPrintTaskRequested(Pri ntManager sender, PrintTaskRequestedEventArgs args) 

{ 

args.Request.CreatePri ntTask("Pri nt Printable Area ”， (requestArgs)=> 

{ 

requestArgs.SetSource(printDocumentSource); 

}); 


void OnPri ntDocumentPagi nate(object sender, PaginateEventArgs args) 

{ 

PrintPageDescription printPageDescription = args■PrintTaskOptions.GetPageDescription(0); 


// Set Padding on outer Border 

double left = printPageDescription.ImageableRect.Left; 
double top = printPageDescription.ImageableRect.Top; 
double right = printPageDescription.PageSize.Width 

- 1 eft - printPageDescription.ImageableRect.Width; 
double bottom = printPageDescription.PageSize.Height 

- top - printPageDescription.ImageableRect.Height; 
border.Padding = new Thi ckness(left , top, right, bottom); 

printDocument.SetPreviewPageCount(1 ， PreviewPageCountType .Final); 

} 

void OnPri ntDocumentGetPrevi ewPageCobject sender, GetPreviewPageEventArgs args) 

{ 

printDocument.SetPreviewPage(args.PageNumber, border); 

} 


void OnPrintDocumentAddPages(object sender, AddPagesEventArgs args) 


printDocument.AddPage(border); 
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} 


} 


printDocument.AddPagesCompleteC); 


The other big difference is the handler for the Paginate event of PrintDocument. The handler 
obtains the PrintPogeDescription structure and calculates a Podding value that it applies to the outer 
Border of the element to be printed. As you can see, the preview displays the red background of the 
outer border to the edge of the paper: 


©HP Deskjet D4100 series on GUESTROOM... 




When the preview is displayed, try switching between Portrait and Landscape. Each change causes 
another call to the Paginate handler and a recalculation of the Podding value for the outer Border. 

The preview obviously doesn’t reflect the limitations of the printer in printing to the paper’s edge. 
Otherwise, that red area wouldn’t be visible at all. I was pleased to discover that the page that actually 
came out of the printer displayed the black inner Border just fine with only a tiny trace of the red 
background of the outer Border, indicating that the ImogeableRect values for this printer are accurate. 

Although a program that prints pictures and other bitmaps might want to print as large as possible 
on the page, most printing applications prefer to set a larger margin — perhaps an inch, more or 
less — either of a fixed size or customizable by the user. In these cases it’s usually not necessary for the 
ImogeableRect property to be accessed at all. 


I’ll have an example of user-supplied margins coming up. 


The Pagination Process 


In the general case, a Windows application prints more than a single page, and the number of pages 
might depend on many factors, for example, the length of a document, font sizes, paper size, page 
margins, and whether the page is in portrait or landscape mode. 
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It is the purpose of the Paginate event handler not only to prepare these pages for preview and 
printing, but to report the number of pages in the document. In some cases pagination might require 
some time, and there are ways to avoid doing it all at once, but it’s easiest if you can do it in one shot. 


Let’s examine a fairly short pagination job by resurrecting the DependencyObjectClassHierarchy 
program from Chapter 4, "Presentation with Panels," and adding a print option to it. As you 
might recall, DependencyObjectClassHierarchy created a TextBlock for every class that derived 
from DependencyObject and put them all in a StockPonel in a ScrollViewer. The XAML file for the 
PrintableClassHierarchy program is the same as in the previous version: 


Project: PrintableClassHierarchy I File: MainPage.xaml (excerpt) 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<ScrollViewer> 

〈StackPanel Name="stackPanel " /> 

</Scrol1 Viewer> 

</Grid> 


I also decided to use a Stack Pan el containing TextBlock children for printing as well, but with a 
profound difference: For the screen, there’s only one StockPonel because it’s in a ScrollViewer. For 
printing, there must be a StockPonel for each page containing only the TextBlock elements for that 
page. 

It is tempting to use the same TextBlock elements for the screen and the printer. In theory you can 
print elements already displayed on the screen, but it is my experience that this technique never really 
works as well as might be hoped. One major restriction is that a particular element cannot have two 
parents. In this example, a printed TextBlock must be a child of a StockPonel for the printer page, so it 
can’t also be a child of a StockPonel on the screen. 

For that reason, the revised version of the class hierarchy program creates a whole separate 
collection of TextBlock elements that it stores in a field named printerTextBlocks. This portion of the 
Main Page class is very similar to the code-behind file in DependencyObjectClassHierarchy except that 
the TextBlock creation code has been split into a separate method for the convenience of creating two 
parallel sets of TextBlock elements. Notice that the printer TextBlock elements are given an explicit 
Foreground of black in the DisployAndPrinterPrep method (renamed from the earlier Display method). 
Most of the printing support is not shown in this excerpt: 


Project: PrintableClassHierarchy I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 
{ 

Type rootType = typeof (DependencyObject) ; 

Typelnfo rootTypelnfo = typeof (DependencyObject) .GetTypelnfoC); 
Li st<Type> classes = new Li st<Type>() ; 

Brush highlightBrush; 

// Printing support 

List<TextBlock> printerTextBlocks = new Li st<TextBlock>() ; 

Brush blackBrush = new SolidColorBrush (Colors. Black); 


public MainPage() 
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this. InitializeComponent(); 
highlightBrush = 

new SolidColorBrush (new UlSetti ngs() .UIE1 ementColor(UIEl ementType .Highlight)); 

// Accumulate all the classes that derive from DependencyObject 
AddToClassLi st(typeof (Windows.UI.Xaml .DependencyObject)) ; 

// Sort them alphabetically by name 
cl asses.Sort((tl, t2)=> 

{ 

return String .Compare(tl.GetTypelnfoO.Name, t2.GetTypelnfoC).Name); 

})； 

// Put all these sorted classes into a tree structure 
ClassAndSubclasses rootClass = new ClassAndSubcl asses(rootType); 
AddToTree(rootClass, classes); 

// Display the tree using TextBlocks added to StackPanel 
DisplayAndPrinterPrepCrootClass, 0); 


} 

void AddToClassList (Type sampleType) 

{ 

Assembly assembly = sampleType.GetTypelnfoC).Assembly; 

foreach (Type type in assembly.ExportedTypes) 

{ 

Typelnfo typelnfo = type.GetTypelnfoC )； 

if (typelnfo.IsPublic && rootTypelnfo.IsAssignableFrom(typelnfo)) 
classes.Add(type); 

} 

} 

void AddToTree(C1 assAndSubclasses parentClass, Li st<Type> cl asses) 

{ 

foreach (Type type in cl asses) 

{ 

Type baseType = type.GetTypelnfoC).BaseType; 

if (baseType == parentClass.Type) 

{ 

ClassAndSubclasses subclass = new ClassAndSubclasses (type); 
parentClass.Subclasses.Add(subclass); 

AddToTree(subClass, classes); 



void Di splayAndPri nterPrep(Cl assAndSubcl asses parentCl ass, int 'indent) 

{ 

Typelnfo typelnfo = parentClass.Type.GetTypelnfoC )； 

// Create TextBlock and add to StackPanel 
TextBlock txtblk = CreateTextBlock(typelnfo, indent); 

StackPanel.Children.Add(txtbl k); 


916 PART Specialties 


// Create TextBlock and add to printer list 
txtblk = CreateTextBlock(typeInfo, indent); 
txtblk.Foreground = blackBrush; 
printerTextBlocks.Add(txtblk); 

// Cal 1 this method recursively for all subclasses 

foreach (ClassAndSubclasses subclass in parentClass.Subclasses) 

DisplayAndPrinterPrep(subclass, indent + 1); 

} 

TextBlock CreateTextBl ock(TypeInfo typelnfo, int indent) 

{ 

// Create TextBlock with type name 
TextBlock txtblk = new TextB1ock() ; 

txtblk.Iniines.Add (new Run { Text = new string( ' ' , 8 * indent) }); 
txtblk.Iniines.Add (new Run { Text = typelnfo.Name }); 

// Indicate if the class is sealed 
if (typelnfo.IsSealed) 

txtblk.Iniines. Add(new Run 

{ 

Text = " (sealed)", 

Foreground = highlightBrush 

}); 

// Indicate if the cl ass can't be instantiated 

IEnumerable<ConstructorInfo> constructorlnfos = typelnfo.DeclaredConstructors; 
int publicConstructorCount = 0; 

foreach (Constructorlnfo constructorlnfo in constructorlnfos) 
if (constructorlnfo.IsPublic) 
publicConstructorCount += 1; 

if (publicConstructorCount == 0) 
txtblk.Iniines.Add (new Run 
{ 

Text = " (non-instantiable)" , 

Foreground = highlightBrush 

}); 

return txtblk; 

} 

} 

The remainder of the printing support is very similar to what you’ve seen before, except that 
there’s more than one page to print. The Paginate method takes on the brunt of the work and stores 
the formatted pages in the printerPages field. Each of these objects is a Border with Podding set to 96 
(one inch) and a child StockPanel with a page worth of the TextBlock elements created earlier. 

Keep in mind that the Paginate handler might be called multiple times as the user waffles between 
Portrait or Landscape mode, and letter or legal page sizes. Because the program is working with a 
fixed collection of TextBlock elements, and because elements are prohibited from having multiple 
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parents, it’s essential for the Paginate method to begin by ensuring that none of these TextBlock 
elements is still a child of a previously created StackPanel. 


Project: PrintableClassHierarchy I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 


PrintDocument printDocument; 

IPrintDocumentSource printDocumentSource; 
List<UIElement> printerPages = new List<UIEl ement>() ; 


public MainPageC) 

{ 

// Create PrintDocument and attach handlers 

pri ntDocument = new Pri ntDocumentO ; 

printDocumentSource = printDocument.DocumentSource; 

printDocument■Paginate += OnPrintDocumentPaginate; 

printDocument.GetPreviewPage += OnPrintDocumentGetPreviewPage; 

printDocument.AddPages += OnPrintDocumentAddPages; 

} 

protected override void OnNavigatedTo(Navi gationEventArgs args) 

{ 

// Attach PrintManager handler 

PrintManager .GetForCurrentView().PrintTaskRequested += OnPrintManagerPrintTaskRequested; 
base.OnNavigatedTo(args); 

} 

protected override void OnNavigatedFrom(Navi gationEventArgs e) 

{ 

// Detach PrintManager handler 

PrintManager .GetForCurrentView().PrintTaskRequested -= OnPrintManagerPrintTaskRequested; 
base. OnNavigatedFrom(e); 

} 

void OnPrintManagerPrintTasl<Requested(Pri ntManager sender, PrintTaskRequestedEventArgs args) 
{ 

args.Request.CreatePrintTask ("Dependency Property Class Hierarchy", (requestArgs)=> 

{ 

requestArgs.SetSource(printDocumentSource); 

}); 

} 

void OnPrintDocumentPagi nate(object sender, PaginateEventArgs args) 

{ 

// Verbosely set some variables for the page margin 

double leftMargin = 96; 

double topMargin = 96; 

double rightMargin = 96; 

double bottomMargin = 96; 
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// Cl ear out previous printerPage collection 
foreach (UIE1 ement printerPage in printerPages) 

((printerPage as Border) .Child as Panel ).Chi 1dren.Clear(); 


printerPages.Cl ear(); 

// Initialize page construction 
Border border = null; 

StackPanel stackPanel = null; 
double maxPageHeight = 0; 
double pageHeight = 0; 


// Look through the list of TextBlocks 

for (i nt index = 0; index < printerTextBlocks.Count; index++) 

{ 

//A null Border object signals a new page 
if (border == null) 

{ 

// Calculate the height available for text 
uint pageNumber = (ui nt)pri nterPages.Count; 
maxPageHeight = 

args.PrintTaskOptions.GetPageDescription(pageNumber)■PageSize.Hei ght; 
maxPageHeight -= topMargin + bottomMargin; 
pageHeight =0; 

// Create StackPanel and Border 
stackPanel = new StackPanel (); 
border = new Border 
{ 

Padding = new Thickness (leftMargin, topMargin, rightMargin, bottomMargin), 
Child = stackPanel 

}； 

// Add to the "list of pages 
printerPages.Add(border); 

} 

// Get the TextBlock and measure it 
TextBlock txtblk = printerTextBlocks[index]; 
txtblk.Measure(Size.Empty); 


// Check if OK to add TextBlock to this page 
if (stackPanel.Children.Count == 0 || 

pageHeight + txtblk.ActualHeight < maxPageHeight) 

{ 

stackPanel.Chi 1dren.Add(txtblk); 

pageHeight += Math .Cei1ing(txtblk.ActualHeight); 
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// Otherwise, it's the end of the page 
else 


// No longer working with this Border object 
border = nul1 ; 

// Reprocess this TextBlock 
i ndex--; 

} 

} 

// Notify about the final page count 

printDocument.SetPreviewPageCount(printerPages.Count, PreviewPageCountType .Final); 

} 

void OnPrintDocumentGetPrevi ewPage(object sender, GetPreviewPageEventArgs args) 

{ 

printDocument.SetPreviewPage(args.PageNumber, printerPages[args.PageNumber - 1]); 

} 

void OnPrintDocumentAddPages(object sender, AddPagesEventArgs args) 

{ 

foreach (UIE1 ement printerPage in printerPages) 
printDocument.AddPage(printerPage); 

printDocument.AddPagesComplete(); 

} 

} 

The strategy for pagination involves calculating a maxPageHeight number from the height of the 
paper page minus one-inch margins on the top and bottom. Another variable named pageHeight is 
increased for every TextBlock added to the Stack Pan el for that page. The method calls the Measure 
method on each TextBlock to calculate its size, and if the height of the TextBlock added to pageHeight 
exceeds maxPageHeight, a new page is required. 

The GetPreviewPoge handler uses the one-based PageNumber property in the event arguments to 
access the corresponding element in the printerPoges list. The Add Pages handler calls AddPage on all 
the pages. 

In the preview, you can examine different pages before printing the whole list: 
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DependencyObject 

AutomationPeer 

FrameworkElementAutomationPeer 
AppBarAutomationPeer 
ButtonBaseAutomationPeer 
ButtonAutomationPeer 
HyperlinkButtonAutomationPeer 
RepeatButtonAutomationPeer 
ToggleButtonAutomationPeer 
CheckBoxAutomationPeer 
RadioButtonAutomationPeer 
CaptureElementAutomationPeer 
ComboBoxItemAutomationPeer 
FlipViewItemAutomationPeer 
GridViewItemAutomationPeer 
GroupItemAutomationPeer 
ImageAutomationPeer 
ItemsControlAutomationPeer 
SelectorAutomationPeer 

ComboBoxAutomationPeer 
FlipViewAutomationPeer 
ListBoxAutomationPeer 
ListViewBaseAutomationPeer 
GridViewAutomationPeer 
ListViewAutomationPeer 
ListBoxItemAutomationPeer 
ListViewItemAutomationPeer 
MediaElementAutomationPeer 
PasswordBoxAutomationPeer 
ProgressRingAutomationPeer 
RangeBaseAutomationPeer 

ProgressBarAutomationPeer 
ScrollBarAutomationPeer 
SliderAutomationPeer 
RichEditBoxAutomationPeer 
RichTextBlockAutomationPeer 
RichTextBlockOverflowAutomationPeer 
ScrollViewerAutomationPeer 
SemanticZoomAutomationPeer 
TextBlockAutomationPeer 
TextBoxAutomationPeer 
ThumbAutomationPeer 



You might have noticed that the pagination logic increases the pageHeight based on each Text- 
Block height with the following code: 


pageHeight += Math .Ceiling(txtblk.ActualHei ght); 

I originally wasn’t using the Math.Ceiling call. The default Fontsize is 11, and ActuolHeight was 
reporting 13.2, and with that my program was giving each StackPanel 65 lines of text to display in the 
9 inches available in portrait mode. However, in the preview, and coming out of the printer, only 62 
lines were visible. The line spacing used to stack the text in the StackPanel was obviously greater than 
13.2, resulting in three TextBlock elements per page being clipped because the resultant StackPanel 
was larger than the space allocated for it. 

Using Math.Ceiling in this case resulted in 61 lines of text per page, which is a little off in the other 
direction, but at least none of the text disappears. 


Still, it’s a little odd. On a video display, of course, it makes perfect sense to align text with pixel 
boundaries for purposes of readability and that’s why coordinates are rounded up to the next highest 
pixel. On a printer, however, there are 600 pixels (or so) to the inch, so the rounding doesn’t need to 
be based on a 96 DPI device. 


Pagination can be very complex, particularly when text is involved. If you encounter chronic 
problems with elements not appearing precisely where you want them on the printer page, you might 
want to switch to using a Canvas. The use of Glyphs rather than TextBlock is popular for sophisticated 
text layout needs, and if you run into a wall using Glyphs, you’ll probably want to explore DirectWrite 
to render to both the screen and the printer page. 


If you prefer going in the other direction — having the Windows Runtime do more of the work in 
determining how text is displayed — then using RichTextBlock (which I discussed in Chapter 16, "Rich 
Text") might be useful. 
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Custom Printing Properties 

The one-inch margins in PrintableClassHierarchy are hard coded. Suppose you want to allow the user 
to select the margins. While we’re at it, let’s give the user the option of setting the font size used for 
printing. 

It is possible without too much trouble to customize the printer setup pane, and to have the 
Windows Runtime do most of the work in creating the appropriate controls and managing input. 

The place to perform this customization is in the handler for the PrintToskRequested event of the 
PrintManoger. So far, this handler has looked like this: 

void OnPrintManagerPrintTaskRequested(Pri ntManager sender, PrintTaskRequestedEventArgs args) 

{ 

args.Request.CreatePrintTask("My Print Task Title "， OnPrintTaskSourceRequested); 

} 

Or, it’s used an anonymous lambda function for the callback: 

void OnPrintManagerPrintTaskRequested(Pri ntManager sender, PrintTaskRequestedEventArgs args) 

{ 

args. Request .CreatePri ntTask("My Print Task Title' 1 ， (requestArgs)=> 

{ 

requestArgs.SetSourceCprintDocumentSource); 

}); 

} 

Whichever way you do it, the CreatePrintTask call actually returns an object of type PrintTask, so 
that object can be saved in a local variable: 

void OnPrintManagerPrintTaskRequested(Pri ntManager sender, PrintTaskRequestedEventArgs args) 

{ 

PrintTask printTask = args.Request.CreatePrintTask("My Print Task Title”， … ); 

} 

From that PrintTask object you can get an object of type PrintToskOptionDetoils via a roundabout 
static call that will probably resist becoming habitual: 

PrintTaskOptionDetai1s optionDetai1s = 

PrintTaskOptionDetai1s .GetFromPrintTaskOptions(printTask.Options); 

PrintToskOptionDetoils and related classes are defined in the Windows.Graphics. Printing-Option Details 
namespace. 

If you want, you can then remove all the options from the first page of the printer setup pane: 
optionDetai1s.DisplayedOptions.ClearC); 
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Now you won’t see the option to change the number of copies or the orientation. You could 
optionally put these back in, perhaps in reverse order: 


optionDetai1s.DisplayedOptions. Add(StandardPri ntTaskOptions .Orientation); 
optionDetai 1 s.Di splayedOptions. Add(StandardPri ntTaskOptions. Copies); 

StandardPrintToskOptions is a static class, and the properties represent standard printer 
options identified with string IDs. StandordPrintTaskOptions.Orientotion is actually the string 
"PageOrientation" and StondardPrintToskOptions.Copies is the string "JobCopiesAIIDocumerits’’. You 
can initialize these options if that is appropriate for your program: 

optionDetai1s.Options [StandardPrintTaskOptions .Orientation].TrySetValue( 

PrintOrientation .Landscape); 

PrintOrientation is one of eleven similar enumerations in Windows.Grophics.Printing. 

You can add a less common option if you think it might be appropriate for your application: 

optionDetai1s.DisplayedOptions.Add (StandardPrintTaskOptions. Col 1ation); 

You can also add your own items. YouYe limited to two types of custom options: a text field, or an 
expanding list of items like the Orientation option. 

Let’s create a new project named CustomizableClassHierarchy. This program is mostly the same as 
PrintableClassHierarchy but defines some customizable values as fields initialized with values that the 
program considers appropriate: 


Project: CustomizableClassHierarchy | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 


// Initial values of custom printer settings 
double fontSize = new TextBlockO . FontSize; 
double 1eftMargin =96; // 1 inch 

double topMargin = 72; // 3/4 inch 

double rightMargin = 96; 
double bottomMargin = 72; 
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These fields are accessed in the handler for the PrintTaskRequested event of the PrintMonager. 
You’ll recall that this event is fired when the user taps the Devices charm, probably in the process of 
selecting a printer: 


Project: CustomizableClassHierarchy I File: MainPage.xaml.es (excerpt) 

void OnPrintManagerPrintTaskRequested(Pri ntManager sender, PrintTaskRequestedEventArgs args) 

{ 

PrintTask printTask = args.Request.CreatePrintTaskC" Dependency Property Class Hierarchy”, 

(requestArgs)=> 

{ 

requestArgs.SetSourceCprintDocumentSource); 

}); 

PrintTaskOptionDetai1s optionDetai1s = 

PrintTaskOptionDetai1s .GetFromPrintTaskOptions(printTask.Options); 

// Add item for font size 

optionDetai1s.CreateTextOption ("idFontSize" , "Font size (in points)"); 
optionDetai1s.DisplayedOptions.Add("i dFontSize") ; 

optionDetails.Options["idFontSize"].TrySetValue((72 * fontSize / 96).ToString()); 

// Add items for page margins 

optionDetai1s.CreateTextOption ("idLeftMargin" , "Left margin (in inches )”）； 
optionDetai1s.DisplayedOptions.Add("i dLeftMargin") ; 

optionDetai1s.Options ["idLeftMargin"] .TrySetValue((leftMargin / 96).ToString()); 

optionDetai1s.CreateTextOption ("idTopMargin" , "Top margin (in inches)"); 
optionDetai1s.DisplayedOptions.Add ("idTopMargi n") ; 

optionDetai1s.Options ["idTopMargin"] .TrySetValue((topMargin / 96).ToString()); 

optionDetai1s.CreateTextOption ("idRightMargin" , "Right margin (in inches )”）； 
optionDetai1s.DisplayedOptions.Add("i dRightMargin") ; 

optionDetai1s.Options ["idRightMargin"] .TrySetValue((rightMargin / 96).ToString()); 

optionDetai1s.CreateTextOption ("idBottomMargin" , "Bottom margin (in inches)"); 
optionDetai1s.DisplayedOptions.Add("i dBottomMargin") ; 

optionDetai1s.Options ["idBottomMargin"] .TrySetValue((bottomMargin / 96).ToString()); 

// Set handler for the option changing 

optionDetai1s.OptionChanged += OnOptionDetai1sOptionChanged; 


Each custom option requires at least two steps and possibly three. First the option must be 
created, in the process giving it an ID string and a label that appears on the printer settings pane. The 
custom option is then added to the DisployedOptions collection. The third step is optional but sets an 
initial value. In my code, the fields storing these values are converted from pixels into points (for the 
font size) and inches (for the margin values). 


The method concludes by setting an event handler for the OptionChanged event. This event will be 
fired for changes to all the printer options, not just the custom options. For text items like these, the 
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event is not fired with every keystroke but only with a press of the Enter key, loss of input focus, or a 
press of the Print button. Here’s what the customized settings pane looks like: 


DependencyObject 
AutomationPeer 

FrameworkElementAutomationPeer 
AppBarAutomationPeer 
ButtonBaseAutomationPeer 
ButtonAutomationPeer 
HyperlinkButtonAutomationPeer 
RepeatButtonAutomationPeer 
ToggleButtonAutomationPeer 
CheckBoxAutomationPeer 
RadioButtonAutomationPeer 
CaptureElementAutomationPeer 
ComboBoxItemAutomationPeer 
FlipViewItemAutomationPeer 
GridViewItemAutomationPeer 
GroupItemAutomationPeer 
ImageAutomationPeer 
ItemsControlAutomationPeer 
SelectorAutomationPeer 

ComboBoxAutomationPeer 
FlipViewAutomationPeer 
List BoxAutomation Peer 
ListViewBaseAutomationPeer 
GridViewAutomationPeer 
ListViewAutomationPeer 
ListBoxItemAutomationPeer 
ListViewItemAutomationPeer 
MediaElementAutomationPeer 
PasswordBoxAutomationPeer 
ProgressRingAutomationPeer 
RangeBaseAutomationPeer 

ProgressBarAutomationPeer 
Scroll BarAutomationPeer 
SliderAutomationPeer 
RichEditBoxAutomationPeer 
RichTextBlockAutomationPeer 
RichTextBlockOverflowAutomationPeer 
ScrollViewerAutomationPeer 
SemanticZoomAutomationPeer 
TextBlockAutomationPeer 
TextBoxAutomationPeer 
ThumbAutomationPeer 

im^tinnPppr 



See the five new items? I know it looks like we’ve gone beyond the limit of the size available for 
custom options, but the list is scrollable. 

Here’s the implementation of the OptionChonged event handler. This is where validation 
occurs, and where you signal that the preview needs to be refreshed with new values, which 
forces your Paginate handler to be called again. The PrintTaskOptionChangedEventArgs class 
defines just one property — named Option Id of type object (but it’s really a string) indicating the 
option that’s changed — but you’ll need to make use of the sender argument as well. That’s the 
PrintToskOptionDetoils object you used during the customization in the PrintTaskRequested handler: 


Project: CustomizableClassHierarchy | File: MainPage.xaml.es (excerpt) 

async void OnOptionDetai1sOptionChanged (Pri ntTaskOptionDetai1s sender, 

PrintTaskOptionChangedEventArgs args) 

{ 

if (args.Optionld == null) 
return ; 

string optionld = args.Optionld.ToString(); 

string strValue = sender.Options[optionld].Value.ToString(); 

string errorText = String .Empty; 

double value = 0; 

switch (optionld) 

{ 

case "idFontSize" : 

if (! Doubl e.TryParse(strValue, out value)) 
errorText = "Value must be numeric ”； 
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else if (value < 4 || value > 36) 

errorText = "Value must be between 4 and 36" ; 
break; 

case "idLeftMargin" : 
case "idTopMargin" : 
case "idRightMargin" : 
case "idBottomMargin" : 

if (! Double .TryParse(strValue, out value)) 
errorText = "Value must be numeric"; 

else if (value < 0 || value > 2 ) 

errorText = "Value must be between 0 and 2" ; 
break; 

} 

sender.Options[optionld].ErrorText = errorText; 

// If there's no error, then invalidate the preview 
if (Stri ng .IsNul10rEmpty(errorText)) 

{ 

await this .Dispatcher.RunAsync(CoreDi spatcherPriority. Normal,()=> 

{ 

printDocument.InvalidatePreview(); 

}); 



If there’s a problem with the input on one of the options, this method needs to set the ErrorText 
property for that option to a short but helpful text string. That string is displayed in red to the user. If 
the ErrorText of any option is set, the Print button also becomes disabled. Here’s what it looks like: 


DependencyObject 
AutomationPeer 

FrameworkElementAutomationPeer 
AppBarAutomationPeer 
Button BaseAutomation Peer 
ButtonAutomationPeer 
HyperlinkButtonAutomationPeer 
RepeatButtonAutomationPeer 
ToggleButtonAutomationPeer 
CheckBoxAutomationPeer 
RadioButtonAutomationPeer 
CaptureElementAutomationPeer 
ComboBoxItemAutomationPeer 
FlipViewItemAutomationPeer 
GridViewItemAutomationPeer 
GroupItemAutomationPeer 
ImageAutomationPeer 
ItemsControlAutomationPeer 
SelectorAutomationPeer 

ComboBoxAutomationPeer 
FlipViewAutomationPeer 
ListBoxAutomationPeer 
ListViewBaseAutomationPeer 
GridViewAutomationPeer 
ListViewAutomationPeer 
ListBoxItemAutomationPeer 
ListViewItemAutomationPeer 
MediaElementAutomationPeer 
Password BoxAutomationPeer 
ProgressRingAutomationPeer 
RangeBaseAutomationPeer 

ProgressBarAutomationPeer 
ScrollBarAutomationPeer 
SliderAutomationPeer 
RichEditBoxAutomationPeer 
RichTextBlockAutomationPeer 
RichTextBlockOverflowAutomationPeer 
ScrollViewerAutomationPeer 
SemanticZoomAutomationPeer 
TextBlockAutomationPeer 
TextBoxAirtomationPeer 
ThumbAutomationPeer 
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Notice how everything below the error message has been shifted down. If the error message you 
supply is longer than a line, it will be wrapped. 

If there's no error, the InvolidotePreview method of the PrintDocument object should be called. 
Notice that a CoreDispatcher is required to force that call to occur in the user-interface thread. This 
OptionChonged handler runs in a secondary thread. 


The In vo lido te Pre view call causes a new Paginate event to be fired on the PrintDocument. This new 
version of the Paginate handler begins by obtaining all the custom values and converting them into 
numbers that it can use. The font size is applied to all the Text Block elements stored for printing, and 
the margin values are used as in the previous version of this method: 


Project: CustomizableClassHierarchy | File: MainPage.xaml.es (excerpt) 

void OnPrintDocumentPagi nate(object sender, PaginateEventArgs args) 

{ 

// Get values of custom settings 
PrintTaskOptionDetai 1 s optionDetails = 

PrintTaskOptionDetai1s .GetFromPrintTaskOptions(args.PrintTaskOptions); 
fontSize = 96 * Double. Parse(optionDetai1s.Options ["i dFontSize"]. Value.ToString()) / 72; 

1 eftMargin = 96 * Double.Parse(optionDetai1s.Options["idLeftMargin"].Value.ToString()); 
topMargin = 96 * Double. Parse(optionDetai1s.Options ["i dTopMargi n"].Value.ToString()); 
rightMargin = 96 * Double .Parse(optionDetai1s.Options ["idRightMargi n"] .Value.ToString()); 
bottomMargin = 96 * Double .Parse(optionDetai1s.Options ["idBottomMargin"] .Value.ToString()); 


// Set FontSize of stored TextBlocks 
foreach (TextBlock txtblk in printerTextBlocks) 
txtblk.FontSize = fontSize; 


With a little more work, you can check that the margin values entered by the user are high enough 
to avoid text appearing in the unprintable area of the page. In the OptionChonged handler you can 
easily access the page description from the PrintToskOptionDetails object: 

Rect imageableRect = sender.GetPageDescription(0).ImageableRect; 
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Printing a Monthly Planner 

Sometimes when I’m working on a long project I like to use printed monthly calendars taped up to 
the wall. These calendars don't need any fancy features — just a lot of white space to write stuff in for 
each day. 

The sole purpose of the PrintMonthlyPlanner program is to print a bunch of monthly calendars in a 
range specified by the user. The main page looks like this: 


Jul 2012 to Sep 2013 

Print 15 Months 


Each month and year is selectable via a FlipView control. The button is enabled only if the start month 
is less than or equal to the end month. The Click handler for the button is implemented with just a 
single line of code: 

await PrintManager .ShowPrintUIAsyncC); 

Although the user normally invokes the charms and Devices pane, a program can do so as well. 
Generally, this option is reserved for programs that print only on special occasions, for example, "Print 
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Ticket Confirmation.’’ Interestingly, calling ShowPrintUIAsync brings up a slightly different pane than 
the Devices charm: 


Print 

PrintMonthlyPlanner 

HP Deskjet D4100 series on G... 


县 


县 


Send To OneNote 2010 


i 


Microsoft XPS Document Writer 


Jul 2012 to Sep 2013 


Print 15 Months 


Because the PrintMonthlyPlanner program is dedicated to printing, the pages that it prints are not 
otherwise displayed by the program and are only visible on screen in the printing pane: 


Ju 


©HP Deskjet D4100 series on GUESTROOM... 




Notice that the Orientation is set to Landscape. The program sets that initial value under the 
assumption that the calendar pages are better formatted in landscape. Each page is printed to the 
very edge of the printable margins. 
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I created a custom control for the user to pick a month and year. This is called MonthYearSelect, 
and the XAML file reveals two templated FlipView controls, both with a horizontal StockPanel as the 
ItemsPanel: 


Project: PrintMonthlyPlanner | File: MonthYearSelect.xaml (excerpt) 

<UserControl … > 

<UserControl.Resources 〉 

<Style TargetType="Fl ipView"> 

〈Setter Property="ItemsPanel "> 
<Setter.Value> 


<ItemsPanelTempiate> 

<StackPanel Orientati on="Verti cal" /> 
</ItemsPanelTempiate> 

</Setter.Value> 

</Setter> 


〈Setter Property="ItemTempl ate"> 

<Setter.Value> 

<DataTemplate> 

<TextBlock Text="{Binding}" VerticalA1i gnment="Center" /> 
</DataTemplate> 

</Setter.Value> 

</Setter> 

</Style> 

</UserControl.Resources 〉 


<Gri d> 

<StackPanel Orientati on="Hori zontal"> 

<F1ipView x:Name="monthFl ipView" 

Selecti onChanged="OnMonthYearSel ectionChanged" /> 


〈TextBlock Text="&#x00A0 ;" /> 


<F1ipView x : Name="yearFl ipView" 

Selecti onChanged="OnMonthYearSel ectionChanged" /> 

</StackPanel> 

</Gri d> 

</UserControl > 


Partially to make use of new features in the Windows Runtime, I decided to make the public 
interface to this class a Calendar object rather than a traditional .NET DateTime. I was hoping to 
make the program generalized for any type of calendar, but the Calendar class doesn’t seem to be 
documented sufficiently to go beyond the standard Gregorian. I couldn’t even discover a way to 
determine if the day of the week should begin on a Sunday (the standard in most places) or Monday 
(used in France, for example). 

I also discovered that Calendar is a class rather than a structure, and it bothered me to be 
generating new Calendar objects with every spin of the FlipView. I decided that the control would 
create just one Calendar object and change the Month and Year properties of that single object. 

But in that case it made no sense for Calendar to be exposed as a dependency property, which is 
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customary with controls, so that’s why the property of type Calendar is a plain old property named 
MonthYeor supplemented with a MonthYeorChanged event to indicate new values of Month or Year: 


Project: PrintMonthlyPlanner | File: MonthYearSelect.xaml.es (excerpt) 

public sealed partial class MonthYearSelect : UserControl 

{ 

public event EventHandler MonthYearChanged; 

public MonthYearSelect() 

{ 

this .InitializeComponent(); 

// Create Calendar with current date 
Calendar calendar = new Cal endar() ; 
calendar.SetToNowO; 

// Fill the first FlipView with the abbreviated month names 
DateTimeFormatter monthFormatter = 

new DateTimeFormatter(YearFormat .None, MonthFormat .Abbreviated, 

DayFormat .None, DayOfWeekFormat .None); 

for (i nt month = 1; month <= 12; month++) 

{ 

string strMonth = monthFormatter.Format( 

new DateTimeOffset (2000, month, 15, 0, 0, 0, TimeSpan .Zero)); 
monthFlipView.Items.Add(strMonth); 

} 

// Fill the second FlipView with years (5 years before current, 25 after) 
for (i nt year = calendar.Year - 5; year <= calendar.Year + 25; year++) 

{ 

yearFlipView.Items.Add(year); 

} 

// Set the FlipViews to the current month and year 
monthFlipView.Selectedlndex = calendar.Month - 1; 
yearFlipView.Selectedltem = calendar.Year; 
this .MonthYear = calendar; 

} 

public Calendar MonthYear { private set; get ; } 

void OnMonthYearSelectionChanged (object sender, SelectionChangedEventArgs args) 

{ 

if (this .MonthYear == null) 
return ; 

if (monthFlipView.Selectedlndex != -1) 

this .MonthYear.Month = (i nt)monthFl ipView.Selectedlndex + 1; 

if (yearFlipView.Selectedlndex != -1) 

this .MonthYear.Year = (int)yearFl ipView.Selectedltem; 
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// Fire the event 
if (MonthYearChanged != null) 

MonthYearChanged(thi s , EventArgs .Empty); 



The MainPage.xaml file instantiates two of these MonthYearSelect controls: 


Project: PrintMonthlyPlanner 丨 File: MainPage.xaml (excerpt) 

<Page … 

FontSize="48"> 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Grid HorizontalAli gnment="Center" 

VerticalA1i gnment="Center"> 

<Grid.ColumnDefinitions> 

<ColumnDefinition Wi dth="Auto" /> 

<ColumnDefinition Width="*" /> 

<ColumnDefinition Wi dth="Auto" /> 

</Grid.ColumnDefinitions> 

<Grid.RowDefinitions> 

<RowDefinition Height="Auto" /> 

〈RowDefi rvi ti on Hei ght="Auto" /> 

</Grid.RowDefinitions> 


<local : MonthYearSelect x : Name="monthYearSel ectl" 

Grid. Row="0" Grid.Col umn="0" 

Hei ght="144" 

VerticalAli gnment="Center" 
MonthYearChanged="OnMonthYearChanged" /> 

〈TextBlock Text=" to&#x00A0;" 

Grid. Row="0" Grid.Col umn="l" 

VerticalA1i gnment="Center" /> 

<local : MonthYearSelect x : Name="monthYearSel ect2" 

Grid. Row="0" Grid.Col umn=__2 n 
Hei ght="144" 

VerticalAli gnment="Center" 
MonthYearChanged="OnMonthYearChanged" /> 

〈Button Name="pri ntButton" 

Content="Pri nt 1 Month" 

Grid. Row="l" Grid.Col umn="0" Grid.Col umnSpan="3" 

FontSi ze="24" 

HorizontalAli gnment="Center" 

Margin="0 24" 

Cli ck="OnPri ntButtonClick" /> 

</Gri d> 

</Gri d> 

</Page> 

This program is a little different from the others in this chapter in that printing is not enabled 
for the duration of the application. Printing is enabled only if the two MonthYearSelect controls are 
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dialed in to an actual range of months. With each change of these two controls, the program needs 
to generate a new label for the Button, determine whether the button should be enabled or disabled, 
and determine whether to attach or detach the PrintTaskRequestecJ event. That logic is much of what’s 
going on in this initial section of the MainPage class: 


Project: PrintMonthlyPlanner | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

PrintDocument printDocument; 

IPrintDocumentSource printDocumentSource; 

List<UIETement> calendarPages = new List<UIEl ement>() ; 
bool printingEnabled; 

public MainPage() 

{ 

this. InitializeComponent(); 

// Create PrintDocument and attach handlers 

printDocument = new PrintDocument() ; 

printDocumentSource = printDocument.DocumentSource; 

printDocument.Paginate += OnPrintDocumentPaginate; 

printDocument.GetPreviewPage += OnPrintDocumentGetPreviewPage; 

printDocument.AddPages += OnPrintDocumentAddPages; 


void OnMonthYearChanged (object sender, EventArgs args) 

{ 

// Calculate number of months and check if it's non-negative 
int pri ntabl eMonths = GetPri ntableMonthCountO ; 

printButton.Content = Stri ng .Format ("Pri nt {0} Month{l}" , printabl eMonths, 

printableMonths > 1 ? "s" : "") ; 
printButton.IsEnabled = printableMonths >0; 

// Attach or detach PrintManager handler 
if (printingEnabled != printableMonths > 0) 

{ 

Pri ntManager printManager = PrintManager .GetForCurrentView(); 
if (pH ntabl eMonths > 0) 

printManager.PrintTaskRequested += OnPrintManagerPrintTaskRequested; 

else 

printManager.PrintTaskRequested -= OnPrintManagerPrintTaskRequested; 
printingEnabled = printableMonths > 0; 

} 

} 

int GetPrintableMonthCountC) 

{ 

Calendar call = monthYearSelectl.MonthYear; 

Calendar cal2 = monthYearSelect2.MonthYear; 

return cal2.Month - cal 1.Month + 1+12 * (cal2.Year - call.Year); 

} 
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async void OnPrintButtonCli ck(object sender, RoutedEventArgs args) 

{ 

await PrintManager .ShowPrintl)IAsync(); 

} 


void OnPrintManagerPrintTaskRequested(Pri ntManager sender, PrintTaskRequestedEventArgs args) 

{ 

// Create PrintTask 

PrintTask printTask = args.Request.CreatePrintTask ("Monthly Planner ”， 

OnPrintTaskSourceRequested); 


// Set orientation to "landscape 

PrintTaskOptionDetai1s optionDetai1s = 

PrintTaskOptionDetai1s .GetFromPrintTaskOptions(printTask.Options); 

PrintOrientationOptionDetai1s orientation = 

optionDetai1s.Options [StandardPrintTaskOptions ■OH entation] as 

PrintOrientationOptionDetai1s ; 


orientation■T rySetValue (Pri ntOrientati on. Landscape); 

} 


void OnPrintTaskSourceRequested (PrintTaskSourceRequestedArgs args) 

{ 

args■SetSource(printDocumentSource); 

} 


Notice also that the PrintTaskRequested handler accesses the Orientation option and initializes it 
to Landscape. This will happen every time the user opens the printer pane. It could be that the user 
really doesn’t want to print these calendar months in landscape mode. You might want to keep track 
of what setting the user ultimately uses by obtaining it, saving it in a field during the Paginate han¬ 
dler, and then using that the next time the printer pane comes up. The user’s preference could even 
be saved in user settings for the next time the program is run. 

Creating the pages is the responsibility of the Paginate handler, which saves them in a field for the 
GetPreviewPage and Add Pages handlers. These pages are built around a Grid with seven columns for 
the seven days of the week, a number of rows based on the number of weeks in the particular month 
(which could range from four in February to six in other months), and one more row for the month 
and year title at the top: 


Project: PrintMonthlyPlanner I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

void OnPrintDocumentPagi nate(object sender, PaginateEventArgs args) 

{ 

// Prepare to generate pages 
uint pageNumbers = 0; 
calendarPages.ClearO ; 

Calendar calendar = monthYearSelectl.MonthYear.Clone(); 
calendar.Day = 1; 

Brush black = new SolidColorBrush (Colors. Black); 
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// For each month 
do 
{ 

PrintPageDescription printPageDescription = 

args.PrintTaskOptions.GetPageDescription(pageNumber); 


// Set Padding on outer Border 

double left = printPageDescription.ImageableRect.Left; 
double top = printPageDescription.ImageableRect.Top; 
double right = printPageDescription.PageSize.Width 

- 1 eft - printPageDescription.ImageableRect.Width; 
double bottom = printPageDescription.PageSize.Height 

- top - printPageDescription.ImageableRect.Height; 

Border border = new Border { Padding = new Thi ckness(left, top, right, bottom) }; 

// Use Grid for calendar cells 
Grid grid = new Gri d(); 
border.Child = grid; 

int numberOfWeeks = (6 + (int)calendar.DayOfWeek + calendar•LastDaylnThisMonth) / 7; 

for (int row = 0; row < numberOfWeeks + 1; row++) 
grid.RowDefinitions.Add (new RowDefinition 
{ 

Height = new Gri dLength(l, GridUnitType .Star) 

}); 

for (int col = 0; col < 7; col++) 

grid.ColumnDefinitions.Add (new ColumnDefinition 

{ 

Width = new GridLength(l, GridUnitType .Star) 

}); 


// Month and year display at top 
Viewbox viewbox = new Viewbox 
{ 

Child = new TextBlock 

{ 

Text = calendar.MonthAsSoloString() + " " + calendar.YearAsStringO , 
Foreground = black, 

FontSize = 96, 

Hori zontal A1 i gnment = HoHzontal Alignment .Center 

} 

}； 

Gnd. Set Row (viewbox, 0); 

Grid. SetColumn(viewbox, 0); 

Grid .SetColumnSpan(viewbox, 7); 
grid.Children.Add(viewbox); 


// Now loop through the days of the month 
for (int day = 1, row = 1, col = (i nt) calendar.DayOfWeek; 
day <= calendar.LastDaylnThisMonth; day++) 

{ 

Border dayBorder = new Border 

{ 

BorderBrush = black, 
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// Avoid double line drawing 
BorderThickness = new Thickness 
{ 

Left = day == 1 || col == 0 ? 1 : 0, 
Top = day - 7 < 1 ? 1 : 0 ， 

Right = 1, 

Bottom = 1 


// Put day of month in upper-left corner 
Child = new TextBlock 
{ 

Text = day.ToString(), 

Foreground = black, 

FontSize = 24 ， 

Hohzontal Alignment = Horizontal A1 ignment ■ Left ， 
VerticalA1ignment = VerticalA1ignment .Top 

} 

}； 

Grid. SetRowCdayBorder, row); 

Grid .SetColumn(dayBorder, col); 
grid.Children.Add(dayBorder); 


if (0 == (col = (col + 1) % 7)) 
row += 1; 

} 

calendarPages.Add(border); 
calendar.AddMonths(l); 
pageNumber += 1; 

} 

while (calendar.Year < monthYearSelect2.MonthYear.Year || 

calendar.Month <= monthYearSelect2.MonthYear.Month); 

printDocument.SetPreviewPageCount(calendarPages.Count, PreviewPageCountType. Final); 

} 

void OnPrintDocumentGetPrevi ewPage(object sender, GetPreviewPageEventArgs args) 

{ 

printDocument.SetPreviewPageCargs.PageNumber, calendarPages[args■PageNumber - 1]); 

} 


void OnPrintDocumentAddPages (object sender, AddPagesEventArgs args) 

{ 

foreach (UIE1 ement calendarPage in calendarPages) 
printDocument.AddPage(calendarPage); 


} 


} 


printDocument.AddPagesComplete(); 


936 PART Specialties 


Printing a Range of Pages 


The next program in this chapter is an experiment that got completely out of control. I wanted to 
demonstrate how to add an option to the printing pane to allow the user to select a variable range 
of pages to print. At the same time, I wanted to show how to share UlElement instances between the 
screen and the printer. 

For this demonstration I chose to revamp the program from Chapter 4 that presented Beatrix 
Potter’s The Tale of Tom Kitten. To allow the pages of this book to be easily printed, I decided that 
each book page should be a separate User Control derivative. For the on-screen rendition, these 
separate User Control pages could simply be assembled in a single scrollable StockPanel. 

There’s nothing really wrong with this scheme except that I ended up with 57 User Control 
derivatives named TomKitten03 through Tom Kitten 59, the number indicating the page from the 
original book. But it turned out I really couldn't use the same instances of these controls on the screen 
and the printer unless I wanted the text or image from each page of the book to be printed in the 
upper-left corner of the printer page, and that was unacceptable. 

Elements that are displayed on the screen are subjected to a layout process that defines their 
relationship to their parent, and in the general case you simply can’t lift these elements out of a visual 
tree and expect that they will render satisfactorily on the printer. And you can't mess around with 
these elements either. You can’t set new properties on them just for the printer because those prop¬ 
erties will affect how they’re displayed on the screen. And you can’t put them into another container 
because that violates the rule that an element can have only one parent. 

I finally realized that I could use the same 57 User Control derivatives for the screen and printer, but 
only if they were separate instances, which means that each of these controls is instantiated twice: one 
in MainPage.xaml for the screen, and again in MainPage.xaml.es for the printer. 

So, in one sense the experiment was a failure because I couldn't simply reuse the instances, but the 
experiment also illuminated the awkwardness of a Visual Studio project that contains 57 User Control 
derivatives! Visual Studio shakes in its boots loading and compiling all these XAML files, and we 
programmers should be nervous as well. This is not the way to make an e-book! 

On the other hand, the program does demonstrate how to add a facility to the printer options to 
select a range of pages to print. 

To allow a uniform set of styles to be applied to the UserControl derivatives in MainPage.xaml 
and as well as the UserControl derivatives instantiated in MainPage.xaml.es, I moved all the Style 
definitions to App.xaml. This makes them available throughout the application. 


Project: PrintableTomKitten | File: App.xaml 
<Application 

x:Cl ass="Pri ntableTomKi tten. App" 

xml ns="http: //schemas.microsoft.com/winfx/2006/xaml/presentati on" 
xml ns :x="http://schemas.microsoft.com/winfx/2006/xaml" 
xml ns : 1 ocal="usi ng : PrintableTomKitten"> 
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<Application.Resources> 

<ResourceDictionary> 

<ResourceDictionary.MergedDicti onaries> 

<ResourceDictionary Source="Common/StandardStyl es.xaml"/> 
</ResourceDictionary.MergedDictionaries> 

<Style x : Key="commonTextStyl e" TargetType="TextBlock"> 

<Setter Property="FontFami ly" Val ue="Century School book" /> 
<Setter Property="FontSize" Value="36" /> 

〈Setter Prope rty=" Foreground" Value="Black" /> 

〈Setter Property="Margi n" Val ue="0 12" /> 

</Style> 


<Style x : Key="paragraphTextStyl e" TargetType="Text Block" 
BasedOn="{Stati cResource commonTextStyl e}"> 

〈Setter Property="TextWrappi ng" Val ue="Wrap" /> 
</Style> 


<Style x : Key="f rontMatterTextStyle" TargetType="Text Block" 
BasedOn="{Stati cResource commonTextStyl e}"> 

〈Setter Property="TextAl ignment" Val ue="Center" /> 
</Style> 


<Style x : Key="i mageStyle" TargetType=" Image"> 

<Setter Prope rty=" Stretch" Val ue="None" /> 

<Setter Property="Hori zontalA1ignment" Val ue="Center" /> 

</Style> 

</ResourceDictionary> 

</Application.Resources> 

</Application> 

The MainPage.xaml file does little more than list all the individual pages of the book in a 
StockPonel. The following listing leaves out the middle section: 


Project: PrintableTomKitten I File: MainPage.xaml (excerpt) 

<Page 

x:Cl ass="Pri ntableTomKitten.MainPage" 

xml ns="http: //schemas.microsoft.com/winfx/2006/xaml/presentation" 
xml ns : x="http: //schemas.microsoft.com/winfx/2006/xaml" 
xml ns : 1 ocal="usi ng : PrintableTomKitten"> 

〈Grid Background="Whi te"> 

<ScrolIViewer> 

<StackPanel Name="bookPageStackPanel " 

MaxWidth="640" 

HorizontalA1i gnment="Center"> 

<local:TomKitten03 /> 

<local:TomKitten04 /> 

<local : TomKitten05 /> 

<local:TomKitten06 /> 

<local:TomKitten07 /> 

<local:TomKitten08 /> 

〈 local:TomKitten09 /> 

<local:TomKittenlO /> 
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<local : TomKittenll /> 
<local : TomKittenl3 /> 
<local : TomKittenl2 /> 

<local:TomKittenl4 /> 
<local : TomKittenl5 /> 
<local : TomKittenl7 /> 
<local : TomKittenl6 /> 

<local:TomKitten50 /> 
<local : TomKitten51 /> 
<local : TomKitten53 /> 
<local : TomKitten52 /> 

<loca1 : TomKitten54 /> 
<local : TomKitten55 /> 
<local : TomKitten56 /> 
<local : TomKitten57 /> 

<local : TomKitten59 /> 
<local : TomKitten58 /> 
</StackPanel> 

〈 /ScrollViewer> 

</Grid> 

</Page> 


Some of these are seemingly out of sequence. As I discussed in Chapter 4, I found it necessary to 
swap some of the text and picture pages to provide a more coherent reading experience. 

The pages containing only an image are quite small: 


Project: PrintableTomKitten | File: TomKitten20.xaml 
<UserControl 

x:Cl ass="Pri ntableTomKitten.TomKitten20" 

xml ns="http: //schemas.microsoft.com/winfx/2006/xaml/presentation" 
xml ns :x="http://schemas.microsoft.com/winfx/2006/xaml"> 

<Image Source="Images/tom20 .jpg" Style="{StaticResource imageStyl e}" /> 
</UserControl > 


Many pages have only one paragraph of text, like the following: 

Project: PrintableTomKitten | File: TomKitten21.xaml 
<UserControl 

x : Cl ass="Pri ntableTomKitten.TomKitten21" 

xml ns="http: //schemas.microsoft.com/winfx/2006/xaml/presentati on" 
xml ns : x="http: //schemas.microsoft.com/winfx/2006/xaml"> 

<Grid VerticalAli gnment="Center" 

MaxWi dth="640"> 

<TextBlock Styl e="{StaticResource paragraphTextStyle}"> 

&#x2003;&#x2003;Tom Kitten was very fat, and he had grown; 
several buttons burst off. His mother sewed them on again. 
</TextBlock> 

</Grid> 

</UserControl> 
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Notice the Vertical A lign ment and MaxWidth settings on the Grid. These settings are for the benefit 
of the printer. The VerticalAlignment setting has no effect when the control is displayed on the 
screen because it’s a child of a StockPanel with a vertical orientation, and the StackPanel itself has a 
MaxWidth setting of 640. 

Those pages with more than a paragraph of text require a StackPanel: 

Project: PrintableTomKitten I File: TomKitten21.xaml 
<UserControl 

x:Cl ass="Pri ntableTomKitten.TomKitten22" 

xml ns="http: //schemas.microsoft.com/winfx/2006/xaml/presentation" 
xml ns : x="http: //schemas.microsoft.com/winfx/2006/xaml"> 

<Grid VerticalAli gnment="Center" 

MaxWidth="640 M > 

<StackPanel> 

<TextBlock Styl e="{StaticResource paragraphTextStyl e}"> 

&#x2003;«&#x2003;When the three kittens were ready, Mrs. 

Tabitha unwisely turned them out into the garden, to be 
out of the way while she made hot buttered toast. 

</TextBlock> 


<TextBlock Styl e="{StaticResource paragraphTextStyl e}"> 

&#x200B;«&#x2003; "Now keep your frocks clean, children! You 
must walk on your hind legs. Keep away from the dirty 
ash-pit, and from Sally Henny Penny, and from the 
pig-stye and the Puddle-Ducks." 

</TextBlock> 

</StackPanel> 

</Grid> 

</UserControl > 

That’s all the XAML you’ll see from this project. 

As you know, it’s very common these days for programs to offer options to print all or part of a 
document. These options are often labeled something like All, Selection, and Custom Range. Because 
I have no concept of selection in the PrintableTomKitten project, my options are limited to "Print all 
pages” and "Print custom range .〃 

It’s also become common for this custom range to contain both individual pages and continuous 
page ranges separated by commas, such as 2-4, 7, 9-11. The constructor of the following 
CustomPogeRange class accepts a string with such a custom page range and resolves the information 
into a list of consecutive pages. For the string "2-4, 7, 9-11", the PogeMopping property is set to the 
list of integers 2, 3, 4, 7, 9, 10,11. If the string is invalid in some way, then PogeMopping is null and 
IsVolid returns false: 


Project: PrintableTomKitten I File: CustomPrintRange.es 

using System; 

using System.Collections.Generic; 
namespace PrintableTomKitten 
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public cl ass CustomPageRange 



// Structure used internally 
struct PageRange 
{ 

public PageRange(i nt from, int to) : thi s() 

{ 


this .From = from; 
this. To = to; 


public int From { private set; get; } 
public int To { private set ; get ; } 


public CustomPageRange(stri ng str, int maxPageNumber) 

{ 

List<PageRange> pageRanges = new List<PageRange>() ; 

string [] strRanges = str.Split( ',' ); 

foreach (string strRange in strRanges) 

{ 

int dashlndex = strRange.IndexOf('-'); 


// Dust one page number 
if (dashlndex == -1) 

{ 

int page; 

if (Int32 .TryParse(strRange.Trim(), out page) && 
page > 0 && page <= maxPageNumber) 

{ 

pageRanges .AddCnew PageRange(page , page)); 

} 

el se 

{ 

return ; 

} 

} 

// Two page numbers separated by a dash 
else 
{ 

string strFrom = strRange.Substring(0, dashlndex); 
string strTo = strRange.Substring(dashlndex + 1); 
int from, to; 


if (Int 32 .TryParse(strFrom.Trim(), out from) && 
Int32 .TryParse(strTo.Trim(), out to) && 
from > 0 && from <= maxPageNumber && 
to > 0 && to <= maxPageNumber && 
from <= to) 

{ 

pageRanges .AddCnew PageRange(f rom, to)); 

} 

el se 


return ; 
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} 


// If we made it to this ， the input string is valid 
this. PageMapping = new Li st<int>() ; 


// Define a mapping to page numbers 
foreach (PageRange pageRange in pageRanges) 

for (int page = pageRange.From; page <= pageRange.To; page++) 
this. PageMapping.Add(page); 

} 

// Zero-based in, one-based out 

public ILi st<i nt> PageMapping { private set ; get ; } 

public bool IsValid 

{ 

get { return this .PageMapping != null; } 

} 



The PrintableTomKitten program uses this class in two places: when it’s validating input that the 
user has entered in the printer options pane, and later in the Paginate event handler. In the second 
case, the CustomPogeRonge object is stored as a field for use by the GetPreviewPage and Add Pages 
handlers. 

Here’s the MainPage.xaml.es file through the OnPrintTaskSourceRequested override. Notice the big 
array at the top containing additional instances of all the book pages solely for printing: 


Project: PrintableTomKitten | File: MainPage.xaml.es (excerpt) 


public sealed partial class MainPage : Page 


PrintDocument printDocument; 

IPrintDocumentSource printDocumentSource; 
CustomPageRange customPageRange; 


UIElement [] bookPages = 


new TomKitten03() , 
new TomKitten07() , 
new TomKittenllO ， 
new TomKittenl5() , 
new TomKittenl9() , 
new TomKitten23() , 
new TomKitten27() , 
new TomKitten31() , 
new TomKitten35() , 
new TomKitten39() , 
new TomKitten43() , 
new TomKitten47() , 
new TomKitten51() , 
new TomKitten55() , 


new TomKi tten04 () ， 
new TomKitten08 () ， 
new TomKi ttenl2() , 
new TomKi ttenl6() , 
new TomKi tten20() , 
new TomKi tten24 () ， 
new TomKi tten28 () ， 
new TomKi tten32() , 
new TomKi tten36() , 
new TomKi tten40() , 
new TomKi tten44() , 
new TomKi tten48() , 
new TomKi tten52() , 
new TomKi tten56 () ， 


new TomKi tten59() 


}； 


new TomKi tten05 () ， 
new TomKi tten09() , 
new TomKi ttenl3() , 
new TomKi ttenl7() , 
new TomKi tten21 () ， 
new TomKi tten25 () ， 
new TomKi tten29() , 
new TomKi tten33() , 
new TomKi tten37() , 
new TomKi tten41() , 
new TomKitten45() , 
new TomKi tten49 () ， 
new TomKi tten53() , 
new TomKi tten57() , 


new TomKi tten06() , 
new TomKi ttenlOO , 
new TomKi ttenl4 () ， 
new TomKi ttenl8() , 
new TomKitten22 (), 
new TomKi tten26() , 
new TomKi tten30() , 
new TomKi tten34 () ， 
new TomKi tten38 () ， 
new TomKitten42 (), 
new TomKi tten46() , 
new TomKi tten50() , 
new TomKi tten54 () ， 
new TomKi tten58() , 
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public MainPage() 


this. InitializeComponent(); 


// Create PrintDocument and attach handlers 

printDocument = new PrintDocument() ; 

printDocumentSource = printDocument.DocumentSource; 

printDocument.Paginate += OnPrintDocumentPaginate; 

printDocument.GetPreviewPage += OnPrintDocumentGetPreviewPage; 

printDocument.AddPages += OnPrintDocumentAddPages; 

} 

protected override void OnNavigatedTo(Navi gationEventArgs args) 

{ 

// Attach PrintManager handler 

PrintManager .GetForCurrentView().PrintTaskRequested += OnPrintManagerPrintTaskRequested; 
base.OnNavigatedTo(args); 

} 

protected override void OnNavigatedFrom(Navi gationEventArgs e) 

{ 

// Detach PrintManager handler 

PrintManager .GetForCurrentView().PrintTaskRequested -= OnPrintManagerPrintTaskRequested; 
base.OnNavigatedFrom(e); 

} 

void OnPri ntManagerPri ntTaskRequested(Pri ntManager sender, PrintTaskRequestedEventArgs args) 

{ 

PrintTask printTask = args.Request.CreatePrintTask("The Tale of Tom Kitten ”， 

OnPrintTaskSourceRequested); 

// Get PrintTaskOptionDetai1s for making changes to options 
PrintTaskOptionDetai1s optionDetai1s = 

Pri ntTaskOpti onDetai 1 s .GetFromPrintTaskOptions(printTask.Options); 


// Create the custom item 

PrintCustomltemListOptionDetai 1 s pageRange = 

optionDetai1s.CreateltemListOption("i dPrintRange" , "Print range") ; 
pageRange.Addltem("i dPrintAl1" , "Print all pages") ; 
pageRange.Addltem("i dPrintCustom" , "Print custom range") ; 


// Add it to the options 

optionDetai1s.DisplayedOptions.Add("i dPrintRange") ; 

// Create a page-range edit item also, but this only 

// comes into play when user selects "Print custom range" 

opti onDetai1s.CreateTextOption("i dCustomRangeEdit" , "Custom Range") ; 
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} 


// Set a handler for the OptionChanged event 

optionDetai1s.OptionChanged += OnOptionDetai1sOptionChanged; 


void OnPrintTaskSourceRequested(Pri ntTaskSourceRequestedArgs args) 
{ 

args■SetSource(printDocumentSource); 

} 


Earlier you saw how to create custom text-entry fields using the CreoteTextOption method of 
PrintToskOptionDetoils. The only alternative to a text-entry field involves the CreateltemListOption 
method shown here. This results in a list of mutually exclusive options similar to the Orientation 
option. Give the method a string ID and a label. The method returns an object of type 
PrintCustomltemListOptionDetails. To that you'll need to add the individual items with ID strings 
and labels and then add those same IDs to the DisployedOptions collection. Here’s what it looks like 
initially: 



But notice also that the PrintToskRequested handler also calls CreoteTextOption to create a 
text-entry field for the custom page range: 


optionDetai1s.CreateTextOption("i dCustomRangeEdit" , "Custom Range") ; 

This is created but it’s not added to the DisployedOptions collection yet. You want this item displayed 
only when the user selects "Print custom range .〃 
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This logic occurs in the OptionChanged handler. If the option ID string is "idPrintCustom”, you then 
want to add the text-entry field identified by the string "idCustomRangeEdit" to the DisplayedOptions 
collection, and if the ID string is "idPrintAII", it must be removed from DisplayedOptions: 


Project: PrintableTomKitten I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 


async void OnOptionDetai1sOptionChanged (Pri ntTaskOptionDetai1s sender, 

PrintTaskOptionChangedEventArgs args) 

{ 

if (args.Optionld == null) 
return ; 


string optionld = args. Opti onld. ToStringO ; 

string strValue = sender.Options[optionld].Value.ToString(); 

string errorText = String. Empty; 

switch (optionld) 

{ 

case "idPrintRange" : 
switch (strValue) 

{ 

case "idPrintAll" : 

if (sender.DisplayedOptions.Contai ns("idCustomRangeEdit")) 
sender.DisplayedOptions.Remove("i dCustomRangeEdit") ; 
break; 

case "idPrintCustom" : 

sender.DisplayedOptions.Add("i dCustomRangeEdit") ; 
break; 

} 

break; 

case "idCustomRangeEdit" : 

// Check to see if CustomPageRange accepts this 
if (!new CustomPageRange(strValue, bookPages.Length).IsValid) 

{ 

errorText = "Use the form 2-4, 7, 9-11" ; 

} 

break; 

} 


sender.Options[optionld].ErrorText = errorText; 

// If no error, then invalidate the preview 
if (Stri ng .IsNullOrEmpty(errorText)) 

{ 

await this. Dispatcher.RunAsync (CoreDi spatcherPriority .Normal,()=> 

{ 

printDocument.InvalidatePreview(); 

}); 

} 

} 

} 
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If the "idCustomRangeEdit" control is visible, you can also receive notifications from that. To 
determine whether the range is valid, the CustomPageRonge constructor is called and a possible error 
text is set. Here’s a page range that is successfully parsed: 



Notice that the page numbers underneath the preview indicate the number of pages that should be 
printed but don’t indicate the actual page numbers the user has selected. I’m not sure that problem 
can really be fixed unless a page range selection is moved into the standard options, and that’s 
something beyond our control. 

Also, notice that the OptionChanged handler does not save the CustomPogeRange object as a 
field. You don’t need to save it in this handler, and you should probably avoid doing so. As the user 
bounces back and forth among the options, it can be tricky to keep track of what’s actually selected 
and visible and what’s not. 

Instead, you can obtain the final settings of the options in the three handlers for the 
Print Document events. In this example, the Paginate handler obtains the settings and saves a 
CustomPogeRange object as a field, which is then accessed by the other two methods: 

Project: PrintableTomKitten | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 
{ 

void OnPrintDocumentPagi nate(object sender, PaginateEventArgs args) 

{ 

// Obtain the print range option 
PrintTaskOptionDetai1s optionDetai1s = 

PrintTaskOptionDetai1s .GetFromPrintTaskOptions(args.PrintTaskOptions); 

string strValue = optionDetai1s.Options ["i dPrintRange"] .Value as string; 

if (strValue == "idPrintCustom") 
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// Parse the print range for GetPreviewPage and AddPages 

string strPageRange = optionDetai1s.Options ["idCustomRangeEdit"] .Value as string; 
customPageRange = new CustomPageRange(strPageRange, bookPages.Length); 

} 

else 

{ 

// Make sure field is null if printing all pages 
customPageRange = null; 

} 

int pageCount = bookPages.Length; 


if (customPageRange != null && customPageRange.IsValid) 
pageCount = customPageRange.PageMapping.Count; 

printDocument.SetPreviewPageCount(pageCount, PreviewPageCountType .Final); 

} 

void OnPrintDocumentGetPrevi ewPage(object sender, GetPreviewPageEventArgs args) 

{ 

int oneBasedlndex = args.PageNumber; 

if (customPageRange != null && customPageRange.IsValid) 

oneBasedlndex = customPageRange.PageMapping[args.PageNumber - 1]; 

printDocument.SetPreviewPage(args.PageNumber, bookPages[oneBasedlndex - 1]); 

} 

void OnPri ntDocumentAddPages(object sender, AddPagesEventArgs args) 

{ 

if (customPageRange != null && customPageRange.IsValid) 

{ 

foreach (i nt oneBasedlndex in customPageRange.PageMapping) 
printDocument.AddPage(bookPages[oneBasedlndex - 1]); 

} 

else 

{ 

foreach (UIE1 ement bookPage in bookPages) 
printDocument.AddPage(bookPage); 

} 

printDocument.AddPagesComplete(); 

} 

} 

I mentioned that I started this printable version of The Tale of Tom Kitten to determine whether 
I could share elements between the screen and printer. If you’d like to see what happens when 
you print those instances of the User Control derivatives displayed from Main Page, simply replace 
bookPages with bookPageStockPanel.Children in the OnPrintDocumentGetPreviewPage and 
On PrintDocumentAdd Pages methods. 
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Where to Do the Big Jobs? 


A program that has the potential of printing many pages might encounter nontrivial pagination 
issues. Perhaps it takes some time to determine exactly how many pages are to be printed. 


In the callback method that you pass to CreotePrintTosk (this is the method I’ve been calling 
OnPrintToskSourceRequested), after calling Set Source on the event arguments, you can use the event 
arguments to obtain a deferral for performing an asynchronous job: 


PrintTaskSourceRequestedDeferral deferral = args.GetDeferral(); 
await BigJoblnvolvingPrintingAsync(); 
deferral.CompleteO; 

In this case, the printing pane with the name of the selected printer is displayed, but under that 
printer name spins a progress ring accompanied by the text "App preparing to print.” The user might 
not enjoy the experience, but it’s a valid way for the application to gain a little time without hanging 
the user-interface thread. 


Also keep in mind that the second argument of the SetPreviewPogeCount method of 
PrintDocument is a member of the PreviewPageCountType enumeration, either Intermediate or 
Final. You don’t need to restrict calls of this method to the body of the Paginate handler. You 
can call it initially with a preliminary page count and then have a background task continu¬ 
ing with the pagination. A Dispatcher to the user-interface thread can make additional calls to 
SetPreviewPogeCount to keep the count updated. 

To assist your application in keeping the user informed of the progress of a long print job, 
PrintTosk defines events named Previewing, Submitting, Progressing, and Completed. 


Printing FingerPaint Art 

Ever since you first started using the various FingerPaint programs in this book, I’m sure you’ve been 
eager to print out your artwork and display it on the refrigerator door. Of course, you can always 
make a screen shot of the FingerPaint screen and print that, but let’s incorporate printing support 
right into FingerPaint itself. 

To have as small an impact as possible on existing FingerPaint code, I decided to derive a class 
from PrintDocument called BitmopPrintDocument. I mentioned earlier that you can do such a thing, 
and although the resultant class has no overridable methods, it does make some object references a 
bit easier. 
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The BitmapPrintDocument class is instantiated in the MainPage constructor: 


Project: FingerPaint I File: MainPage.xaml.es (excerpt) 

public MainPageO 


// Create a PrintDocument derivative for handling printing 
new BitmapPrintDocument (() => { return bitmap; }); 


Notice that odd argument to the BitmapPrintDocument constructor! The problem is that the 
BitmapPrintDocument class definitely requires a reference to the WriteobleBitmap field named bitmap 
if it is to print that bitmap, but it can't simply be passed to the BitmapPrintDocument constructor. That 
bitmap field changes whenever the program loads an image from a file or the clipboard or when it 
creates a new canvas. For that reason, I’ve defined the constructor of BitmapPrintDocument with a 
parameter of type Func<BitmopSource> so that whenever the BitmapPrintDocument needs the cur¬ 
rent bitmap, it can simply call back into MainPage. 

BitmapPrintDocument saves that argument in a field and performs the standard initialization: 


Project: FingerPaint | File: BitmapPrintDocument.es (excerpt) 

public class BitmapPrintDocument : PrintDocument 

{ 

Func<BitmapSource> getBitmap; 

IPrintDocumentSource printDocumentSource; 

// Element to print 
Border border = new Border 
{ 

Child = new Image () 

}； 


public BitmapPrintDocument (Func<BitmapSource> getBitmap) 

{ 

this. getBitmap = getBitmap; 

// Get IPrintDocumentSource and attach event handlers 

printDocumentSource = this. DocumentSource; 

this .Paginate += OnPaginate; 

this. GetPreviewPage += OnGetPreviewPage; 

this. AddPages += OnAddPages; 


// Attach PrintManager handler 

Pri ntManager.GetForCurrentView().PrintTaskRequested += 

OnPrintDocumentPrintTaskRequested; 


} 
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The PrintTaskRequested handler is the first place where the bitmap is required because it sets the 
initial orientation of the printer page to be consistent with the orientation of the bitmap: 

Project: FingerPaint | File: BitmapPrintDocument.es (excerpt) 

async void OnPrintDocumentPrintTaskRequested(Pri ntManager sender, 

PrintTaskRequestedEventArgs args) 

{ 

PrintTaskRequestedDeferral deferral = args.Request.GetDeferral(); 

// Obtain PrintTask 

PrintTask printTask = args.Request.CreatePrintTask("Fi nger Paint", 

OnPrintTaskSourceRequested); 

// Probably set orientation to landscape 
PrintTaskOptionDetai1s optionDetai1s = 

PrintTaskOptionDetai1s .GetFromPrintTaskOptions(printTask.Options); 

PrintOrientationOptionDetai1s orientation = 

optionDetai1s.Options [StandardPrintTaskOptions .Orientation] as 

PrintOrientationOptionDetai1s ; 

bool bitmapIsLandscape = false; 

await border.Dispatcher.RunAsyncCCoreDi spatcherPriori ty. Normal,()=> 

{ 

BitmapSource bitmapSource = getBitmapO; 

bitmapIsLandscape = bitmapSource.PixelWidth > bitmapSource.PixelHeight; 

})； 

ori entation.TrySetValue(bitmapIsLandscape ? PrintOrientation .Landscape : 

PrintOrientation .Portrait); 

deferral.CompleteC); 

} 

Notice that a CoreDispotcher object must be used to access the bitmap in the user-interface 
thread. The other event handlers should look familiar at this point, except that references to the 
PrintDocument methods are simply references to methods of this: 

Project: FingerPaint I File: BitmapPrintDocument.es (excerpt) 

void OnPrintTaskSourceRequested (Pri ntTaskSourceRequestedArgs args) 

{ 

args.SetSource(printDocumentSource); 

} 

void OnPaginate (object sender, PaginateEventArgs args) 

{ 

PrintPageDescription pageDesc = args.PrintTaskOptions.GetPageDescription(O); 
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// Get the Bitmap 

(border.Child as Image) .Source = getBitmapC); 


// Set Padding on the Border 

double left = pageDesc.ImageableRect.Left; 

double top = pageDesc.ImageableRect.Top; 

double right = pageDesc.PageSize.Width - left - pageDesc.ImageableRect.Width; 
double bottom = pageDesc.PageSize.Height - top - pageDesc.ImageableRect.Height; 
border.Padding = new Thickness (left, top, right, bottom); 

this. SetPreviewPageCount(l, PreviewPageCountType .Final); 

} 


void OnGetPrevi ewPage(object sender, GetPreviewPageEventArgs args) 

{ 

this. SetPreviewPage(args.PageNumber, border); 

} 


void OnAddPages (object sender, AddPagesEventArgs args) 

{ 

this .AddPage(border); 
this. AddPagesCompl ete(); 


The Image element has its default Stretch mode of Uniform, which lets the bitmap be displayed as 
large as possible while still respecting the aspect ratio. In addition, the OnPoginate method sets the 
Podding property of the Border to avoid only the unprintable area of the page because of course you 
want your finger paintings printed as large as the printer will allow. 
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CHAPTER 18 

Sensors and GPS 


I n recent years, computers have evolved to develop new sensory organs. This isn’t the plot of a 
new movie! Many of our computers — and particularly tablets and other mobile devices — contain 
hardware that lets the machine know its orientation in 3D space, its location on the face of the Earth, 
the amount of ambient light in the vicinity, and even the speed that the computer is turning in the 
user’s hands. 

These pieces of hardware are referred to collectively as sensors, and the software interface to 
them can be found largely in the Windows.Devices.Sensors namespace, while the classes that help 
a program determine its geographical location are in the Windows.Devices.Geolocotion namespace. 
The hardware that facilities this latter job is often referred to informally as GPS (after the Global 
Positioning System implemented with satellites), but a computer can also often determine its 
geographic location through a network connection. 

This chapter focuses on the information available from the SimpleOrientotionSensor, Accelerometer, 
Compass, Inclinometer, OrientotionSensor, and Geolocator classes, but I’m afraid 111 be skipping the less 
commonly used LightSensor and Gyrometer classes, the latter of which measures the angular velocity 
of the computer. 


To get the full benefit from this chapter, you’ll need to grab the computer running these 
sample programs and move it around in space, even holding it over your head. If your Windows 8 
development machine is pretty much anchored to a desk like mine is, you’ll want to get a tablet such 
as the Microsoft Surface and deploy programs on it remotely, as Tim Heuer discusses in his blog entry, 
http://timheuer.com/blog/archive/2012/10/26/rernote-debugging-windows-store-apps-on-surface- 
arm-devices.aspx. 

Some of the sample programs in this chapter are adapted from articles I wrote about Windows 
Phone 7.5 sensors in the June through December 2012 issues of MSDN Magazine. 


Orientation and Orientation 


As its name declares, the simplest of the sensors that I’ll be discussing is SimpleOrientationSensor, 
which gives your program a rough idea how the computer is oriented in 3D space but without details. 
To instantiate the SimpleOrientationSensor class, you call a static method: 


SimpleOrientationSensor simpleOrientationSensor = SimpleOrientationSensor .GetDefault(); 
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You’ll only do this once in an application, so this code can appear as a field definition to allow 
access to that object within the whole class. If the SimpleOrientotionSensor.GetDefoult method returns 
null, the computer doesn’t have a facility to determine its orientation. 

At any time, you can obtain a value indicating the current orientation from the 
SimpleOrientationSensor object: 

SimpleOrientation simpleOrientation = simpleOrientationSensor.GetCurrentOrientation(); 
SimpleOrientation is an enumeration with six members: 

■ Not Roto ted 

■ Rotated90DegreesCounterclockwise 

■ Rototedl80DegreesCounterclockwise 

■ Rotated270DegreesCounterclockwise 

■ Faceup 

■ Facedown 

The limitation of the information to these six members is the "simple” part of the 
SimpleOrientationSensor. 

You can also be notified through an event when the orientation changes. Set a handler for the 
OrientationChanged event like so: 

simpleOrientationSensor.OrientationChanged += OnSimpleOrientationChanged; 

This event fires only when the orientation changes, which won’t happen if the computer remains 
relatively still. If you need an initial value, call the GetCurrentOrientation method in addition to setting 
the event handler. 

This event handler runs in its own thread, so to interact with the user-interface thread you’ll need 
to use a CoreDispatcher object: 

async void OnSimpleOrientationChanged(Si mpleOrientationSensor sender, 

SimpleOrientationSensorOrientationChangedEventArgs args) 

{ 

await this .Dispatcher.RunAsync(CoreDi spatcherPriority. Normal,()=> 

{ 

})； 

} 

The event argument with the excessively long name has an Orientation property of the 
SimpleOrientation enumeration type and a Timestamp property of type DateTimeOffset. 

You might be asking: Don’t I already have this orientation information? Isn’t it provided 
by the Windows.Grophics.Display namespace? Don't I use the DisplayProperties class and its 
NotiveOrientotion and CurrentOrientation static properties and the OrientationChanged event 
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for orientation information? You’ll recall that those two static properties return members of the 
DisployOrientotions enumeration type: 

■ Landscape 

■ Portrait 

■ LandscopeFlipped 

■ PortroitFlipped 

The SimpleOrientationSensor and DisplayProperties classes are certainly related, but it's important 
to understand how: The SimpleOrientationSensor class indicates how the computer is oriented in 3D 
space. The DisployProperties.CurrentOrientotion property indicates how Windows has compensated 
for this computer orientation by automatically reorienting your program’s window. In other words, 
SimpleOrientationSensor reports a hardware orientation, and DisplayProperties.CurrentOrientotion 
reports a software orientation that has occurred in response to the hardware orientation. 

The OrientationAndOrientation project is intended to help differentiate between the two types 
of orientation. The XAML file defines just a few TextBlock elements for labels and to display some 
information: 


Project: OrientationAndOrientation | Project: MainPage.xaml (excerpt) 

〈Page .■■ FontSi ze="24"> 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Grid HorizontalAli gnment="Center" 

VerticalA1i gnment="Center"> 

<Grid.RowDefiniti ons> 

<RowDefinition Hei ght="Auto" /> 

<RowDefinition Hei ght="Auto" /> 

</Grid.RowDefiniti ons> 

<Grid.ColumnDefinitions> 

<ColumnDefinition Wi dth="Auto" /> 

<ColumnDefinition Wi dth="Auto" /> 

</Grid.ColumnDefini ti ons> 


<TextBlock Text="Si mpleOrientationSensor:&#x00A0;" 
Grid.Row="0" 

Grid.Column="0" /> 

<TextBlock Name="ori entationSensorTextBlock" 

Grid.Row="0" 

Grid.Column="l" 

TextAlignment="Ri ght" /> 

<TextBlock Text="Di splayProperties.CurrentOrientation:&#x00A0; 
Grid.Row= ,, l" 

Grid.Column="0" /> 


<TextBlock Name="di splayOrientationTextBlock" 
Grid.Row="l M 
Grid.Col umn="l" 

TextAlignment="Ri ght" /> 

</Grid> 

</Gri d> 

</Page> 
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The code-behind file defines two methods for the sole purpose of setting the two TextBlock 
elements in the second column of the Grid. These two methods are called both from the constructor 
to set initial values and from two event handlers: 

Project: OrientationAndOrientation I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

SimpleOrientationSensor simpleOrientationSensor = SimpleOrientationSensor .GetDefault(); 

public MainPageC) 

{ 

this .InitializeComponent(); 

// SimpleOrientationSensor initialization 
if (simpleOrientationSensor != null) 

{ 

SetOrientationSensorText(simpleOrientationSensor.GetCu rrentOrientation()); 
simpleOrientationSensor.OrientationChanged += OnSimpleOrientationChanged; 

} 

// DisplayProperties initialization 

SetDisplayOrientationText (Di splayProperties .CurrentOrientation); 

DisplayProperties .OrientationChanged += OnDisplayPropertiesOrientationChanged; 

} 

// SimpleOrientationSensor handler 

async void OnSimpleOrientationChanged (Si mpleOrientationSensor sender, 

SimpleOrientationSensorOrientationChangedEventArgs args) 

{ 

await this .Dispatcher.RunAsync(CoreDi spatcherPriority. Normal,()=> 

{ 

SetOrientationSensorText(args.Orientati on); 

})； 

} 

voi d SetOri entati onSensorText (Si_ mpl eOri entati on si mpl eOri entati on) 

{ 

ori entati onSensorText Block. Text = simpleOrientation.ToStringO ; 

} 

// DisplayProperties handler 

void OnDisplayPropertiesOrientati onChanged(object sender) 

{ 

SetDisplayOrientationText (Di splayProperties. CurrentOrientati on); 

} 

void SetDisplayOrientationText (Di splayOrientations displayOrientation) 

{ 

di spl ayOri entati onText B"l ock.Text = di spl ayOri entati on .ToStri ng(); 

} 

} 

Notice that the SimpleOrientationSensor is instantiated as a field but the constructor checks for a 
non-null value before accessing the object. 
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If you run this program on a tablet that has a native landscape orientation — that is, the 
DisployProperties.NativeOrientotion property returns DisployOrientations.Landscape — and if you 
haven’t done anything to prohibit Windows 8 from making orientation changes (such as putting the 
tablet in a docking station), then you’ll generally f\r\d the following correspondence between the two 
orientation indicators as you progressively rotate the tablet in a clockwise direction: 


SimpleOrientationSensor 

DisplayProperties.CurrentOrientation 

Not Roto ted 

Landscape 

Rototed270DegreesCounterClockwise 

Portrait 

Rototedl80DegreesCounterClockwise 

LandscapeFlipped 

Rototed90DegreesCounterClockwise 

PortraitFlipped 


The SimpleOrientationSensor also reports Faceup and Facedown values, which have no 
correspondences in the DisployOrientotions enumeration. 


While the preceding table is roughly true for a tablet that has a native landscape orientation, a 
mobile device that has a native portrait orientation will have the following correspondences: 


SimpleOrientationSensor 

DisplayProperties.CurrentOrientation 

Not Rota ted 

Portrait 

Rotated270DegreesCounterClockwise 

LandscapeFlipped 

Rotatedl80DegreesCounterClockwise 

PortraitFlipped 

Rotated90DegreesCounterClockwise 

Landscape 


Moreover, an application can request that Windows not make any compensation for 
the orientation of the computer, either in the Package.appxmanifest file or in software by 
setting the DisplayProperties.AutoRototionPreferences property. In that case it’s likely that 
DisplayProperties.CurrentOrientotion will never change while the application is running. Some 
tablets also have a hardware switch that users can toggle to stop Windows from automatically 
rotating the display. In such cases, you might even see something like this: 


SimpleOrientationSensor 

DisplayProperties.CurrentOrientation 

Not Rota ted 

PortraitFlipped 

Rotated270DegreesCounterClockwise 

PortraitFlipped 

Rotatedl80DegreesCounterClockwise 

PortraitFlipped 

Rotated90DegreesCounterClockwise 

PortraitFlipped 


If you want to perform your own compensation for orientation, you can do so. You can instruct 
Windows not to perform any orientation changes, and then use the SimpleOrientationSensor to 
determine how the computer is really oriented. However, keep in mind that what you are giving 
Windows in the Package.appxmanifest file and the DisployProperties.AutoRototionPreferences is 
only what you prefer and not what Windows will actually do, so you might need to make a further 
adjustment if Windows has oriented the display contrary to your preferences. 
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Probably the safest approach to prevent auto-rotation is to set 
DisployProperties.AutoRotationPreferences to DisployProperties.NotiveOrientation, as 
I’ll begin doing later in this chapter. 

Acceleration, Force, Gravity, and Vectors 


Internally, the SimpleOrientotionSensor undoubtedly has access to a piece of hardware called an 
accelerometer. An accelerometer is a device that measures acceleration, and at first it might seem as if 
knowing the acceleration of the computer is not very useful. However, we know from basic physics — 
specifically, Isaac Newton’s second law of motion — that 

F=ma 

Force equals mass times acceleration, and one force that is very hard to escape is the force of gravity. 
Most of the time the computer’s accelerometer measures gravity and answers the basic question, 
"Which way is down?" 

You can get at the accelerometer hardware more directly through the Accelerometer class. To 
instantiate the Accelerometer class, you’ll use a static method with the same name as the one in 
SimpleOrientotionSensor. 

Accelerometer accelerometer = Accel erometer.GetDefaultC); 

If the Accelerometer.GetDefoult method returns null, the computer doesn’t have an accelerometer or 
Windows 8 doesn't know about it. If your application can’t run right without an accelerometer, you'll 
need to notify the user that it’s missing. 

At any time, you can obtain a current value of the Accelerometer: 

AccelerometerReading accelerometerReading = accelerometer.GetCurrentReading(); 

The similar method in SimpleOrientationSensor is named GetCurrentOrientation. 

It’s probably a good idea to check if the value returned from GetCurrentReoding is null. 
AccelerometerReoding defines four properties: 

■ AccelerotionX of type double 

■ AccelerotionY of type double 

■ AccelerotionZ of type double 

■ Timestamp of type DateTimeOffset 

The three double values together constitute a 3D vector that points toward the Earth relative to the 
device. More on this shortly. 
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You can also attach an event handler to the Accelerometer object: 
accelerometer.ReadingChanged += OnAccelerometerReadingChanged; 

The similar event in SimpleOrientationSensor is named OrientotionChonged. Like Orientation Changed, 
the ReodingChonged handler runs in a separate thread, so it’s likely you’ll be handling it like so: 


async void OnAccelerometerReadingChangedCAccel erometer sender, 

AccelerometerReadingChangedEventArgs args) 

{ 

await this. Dispatcher.RunAsync(CoreDi spatcherPriority. Normal,()=> 

{ 

}); 

} 

Jhe A ccelerometerReodingChangedE vent A rgs defines a property named Reading of type 
AccelerometerReading, the same as the object returned from GetCurrentReading. 

How often can you expect the ReodingChonged handler to be called? If the computer is still, it 
might not be called at all! For that reason, if you need an initial Accelerometer reading, you should call 
GetCurrentReading at the outset. 

If the computer is being moved and changing orientation in space, the ReodingChonged handler 
is called when the value changes (within certain criteria) but no more frequently than an interval in 
milliseconds that you can obtain from the Reportlnterval property of Accelerometer. I see a default 
value of 112, which means that the ReodingChonged method is called no faster than about nine times 
a second. 

You can set Reportlnterval to another value if you’d like, but no lower than the value returned 
from the Minimum Reportlnterval property, which I’ve found is 16 milliseconds, or about 60 times 
per second. Set Reportlnterval to Minimum Reportlnterval to get the maximum amount of data; set 
Reportlnterval to zero to return to the default setting. 

All the other sensor classes in Windows.Devices.Sensors have the same software interface as 
Accelerometer. They all have the following members: 

■ static GetDefault method 

■ GetCurrentReading instance method 

■ Reportlnterval property 

■ get-only Minimum Reportlnterval property 

■ ReodingChonged event 

Only SimpleOrientationSensor is different from the others. 

If the computer is still, the AccelerotionX, AccelerationY, and AccelerotionZ properties of the 
AccelerometerReading class define a vector that points toward the center of the Earth. Vectors are 
generally notated with boldface coordinates such as (x, y, z) to differentiate them from points (x, y, z) 
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in 3D space. A point is a location in space; a vector is a direction and a magnitude. Vectors and points 
are related, of course: The direction of the vector (x, y, z) is the direction from the point (0, 0, 0) to 
the point (x, y, z), and the magnitude of the vector is the length of that line. But the vector is not the 
line itself and has no location. 

The magnitude of a vector can be calculated with the three-dimensional form of the Pythagorean 
Theorem: 



Any three-dimensional vector must be relative to a particular three-dimensional coordinate 
system, and the vector obtained from the AccelerometerReoding object is no exception. For a tablet 
with a native landscape orientation, that coordinate system is imposed on the hardware of the device, 
as shown here: 



Notice that the direction of increasing Y is up, which is opposite of the convention when working 
with two-dimensional graphics. The positive Z axis points out of the screen. This convention is often 
referred to as a "right-hand” coordinate system. If you point the index finger of your right hand in the 
direction of positive X and your middle finger in the direction of positive Y, your thumb points toward 
positive Z 

Or, if you curl the fingers of your right hand in the direction necessary to rotate the positive X 
axis into the positive Y axis, your thumb points in the direction of the positive Z axis. This works with 
any pair of axes in the order X ; Y, Z: Curl your right-hand fingers to rotate the positive Y axis into the 
positive Z axis, and your thumb points toward positive X. Or curl your right-hand fingers to rotate the 
positive Z axis into the positive X axis, and your thumb points toward positive Y. 

The right-hand rule can also be used to determine the direction of rotations around the axis. For 
rotations around the X axis (for example), point your right-hand thumb in the direction of positive X, 
and your fingers curl in the direction of positive rotation angles around that axis. 
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For devices with a native portrait orientation, the coordinate system is the same from the user’s 
perspective: 



Although I haven't been able to confirm this, the coordinate system for conventional laptops is 
documented as being based on the keyboard rather than the screen. The X axis is along the width 
of the keyboard, the Y axis is along the height of the keyboard, and the Z axis points out of the 
keyboard. 


This coordinate system is fixed to the hardware of the device, and the Accelerometer vector points 
toward the center of the Earth relative to that coordinate system. For example, when a tablet is held 
upright in its native orientation, the acceleration vector points in the -Y direction. The magnitude of 
the vector is approximately 1, so the vector is somewhere in the region (0, -1, 0). When the device is 
lying on a flat surface like a table with the screen pointing up, the vector is somewhere in the region 
of ( 0 , 0 ,- 1 ). 


The magnitude of 1 indicates that the vector is in units of g, which is the acceleration caused by the 
force of gravity on the surface of the Earth, or about 32 feet per second squared. Take your tablet to 
the moon, and the magnitude will instead be in the vicinity of 0.17. Put your tablet into free fall (if you 
dare), and the magnitude of the acceleration vector will drop to zero until it hits the ground. 
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Text= 'Accelerometer X 
Text="Accel erometer Y 
Text="Accel erometer Z 
Text="Magni tude : " 


Text= 'Simple Onentation : /> 


<Grid HorizontaIA1lgnment= Center 
VerticalA1i gnment="Center"> 

<Grid.RowDefinitions> 

〈RowDefinition Height="Auto" /> 
〈RowDefinition Height="Auto" /> 
〈RowDefinition Height="Auto" /> 
〈RowDefinition Hei ght="Auto" /> 
〈RowDefinition Height="Auto" /> 
</Grid.RowDefinitions> 

<Grid.ColumnDefinitions> 

<ColumnDefinition Wi dth="Auto" /> 
<ColumnDefinition Wi dth="Auto" /> 
</Grid.ColumnDefinitions> 

〈TextBlock Grid. Row="0" Grid.Col umn="0 M 
〈TextBlock Grid.Row="l" Grid.Col umn="0 M 
〈TextBlock Grid. Row="2" Grid.Col umn="0" 
〈TextBlock Grid. Row="3" Grid.Col umn="0 M 
Margi n="24 24" /> 

<TextBlock Grid. Row="4" Grid.Col umn="0 M 


<TextBlock Grid■Row= '0” Grid.Column= '1" Name= 'accelerometerX ' 
TextAlignment="Ri ght" /> 

<TextBlock Grid.Row="l" Grid.Column="l" Name="accel erometerY" 
TextAlignment="Ri ght"/> 

<TextBlock Grid.Row="2" Grid.Column="l" Name="accel erometerZ" 
TextAlignment="Ri ght"/> 

<TextBlock Grid.Row="3" Grid.Column="l" Name="magm' tude" 

TextAlignment="Ri ght" 

VerticalA1i gnment="Center" /> 

<TextBlock Grid.Row="4" Grid.Column="l" Name="si mpleOrientation" 
TextAlignment="Ri ght" /> 

</Grid> 

</Gri d> 

</Page> 


Here’s a program called AccelerometerAndSimpleOrientation that displays values from the 
Accelerometer and the SimpleOrientotionSensor. The XAML file contains a bunch of Text Block elements 
for labels and awaiting values from the code-behind file: 

Project: AccelerometerAndSimpleOrientation | File: MainPage.xaml (excerpt) 

<Page … > 

<Page.Resources 〉 

〈Style TargetType="TextBlock"> 

〈Setter Property="FontSi ze" Value="24" /> 

〈Setter Property="Margi n" Value="24 12 24 12" /> 

</Style> 

</Page.Resources> 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 


> > > 
/ / / 
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The code-behind file has a couple more amenities than the previous one. If the Accelerometer or 
SimpleOrientationSensor cannot be instantiated, the program reports that to the user. Also, it’s a good 
idea not to have an Accelerometer running when a program isn’t using it because it could contribute 
to battery drain. To symbolize application politeness, this program attaches the handlers in the 
OnNavigatedTo override and detaches them in On Naviga ted From. Otherwise, it’s structurally quite 
similar to the previous program: 


Project: AccelerometerAndSimpleOrientation | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

Accelerometer accelerometer = Accelerometer .GetDefaultO; 

SimpleOrientationSensor SimpleOrientationSensor = SimpleOrientationSensor .GetDefault(); 


public MainPageO 

{ 

this .Ini tializeComponent(); 
this. Loaded += OnMainPageLoaded; 


async void OnMainPageLoaded (object sender, RoutedEventArgs args) 

{ 

if (accelerometer == null) 

await new MessageDial ogC'Cannot start Accelerometer") .ShowAsyncO ; 
if (SimpleOrientationSensor == null) 

await new MessageDi al ogC'Cannot start SimpleOrientationSensor") .ShowAsyncO ； 

} 

// Attach event handlers 

protected override void OnNavigatedTo(Navi gationEventArgs args) 

{ 

if (accelerometer != null) 

{ 

SetAccelerometerText(accelerometer.GetCurrentReadingO); 
accelerometer.Readi ngChanged += OnAccelerometerReadingChanged; 

} 

if (SimpleOrientationSensor != null) 

{ 

SetSimpleOrientationText(simpleOrientationSensor.GetCurrentOri entation()); 
simpleOrientationSensor.OrientationChanged += OnSimpleOrientationChanged; 

} 

base. OnNavigatedTo(args); 
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// Detach event handlers 

protected override void OnNavigatedFrom(Navi gationEventArgs args) 

{ 

if (accelerometer != null) 

accelerometer.ReadingChanged -= OnAccelerometerReadingChanged; 
if (simpleOrientationSensor != null) 

simpleOrientationSensor.OrientationChanged -= OnSimpleOrientationChanged; 
base. OnNavigatedFrom(args); 


// Accelerometer handler 

async void OnAccelerometerReadingChanged(Accel erometer sender, 

AccelerometerReadingChangedEventArgs args) 

{ 

await this .Dispatcher.RunAsync(CoreDi spatcherPriority. Normal,()=> 

{ 

SetAccelerometerTextCargs.Reading); 

}); 

} 

void SetAccelerometerText (AccelerometerReading accelerometerReading) 

{ 

if (accelerometerReading == null) 
return ; 

accelerometerX.Text = accelerometerReading.AccelerationX.ToStri ng("F2") ; 
accelerometerY.Text = accelerometerReading.AccelerationY.ToStri ng("F2") ; 
accelerometerZ.Text = accelerometerReading.AccelerationZ.ToStri ng("F2") ; 
magnitude.Text = 

Math . Sqrt(Math .Pow(accelerometerReading.AccelerationX, 2) + 

Math .Pow(accelerometerReading.AccelerationY, 2) + 

Math .Pow(accelerometerReading.AccelerationZ, 2)).ToStri ng("F2") ; 


// SimpleOrientationSensor handler 

async void OnSimpIeOrientationChanged(Si mpleOrientationSensor sender, 

SimpleOrientationSensorOrientationChangedEventArgs args) 

{ 

await this .Dispatcher.RunAsync(CoreDi spatcherPriority. Normal,()=> 

{ 

SetSimpleOrientationText(args.Orientation); 

})； 

} 

void SetSimpleOrientationText (Si mpleOrientation simpleOrientation) 

{ 

this .simpleOrientation.Text = simpleOrientation.ToString(); 

} 

} 
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Here’s the program running on the tablet I’m using to write this book while the tablet sits in its 
docking station: 


Accelerometer X: 

0.01 

Accelerometer Y: 

-0.81 

Accelerometer Z: 

-0.50 

Magnitude: 

0.95 

Simple Orientation: 

NotRotated 


Don’t be alarmed at seeing magnitudes that are not precisely equal to 1. It doesn’t mean that 
you’ve unknowingly drifted away from the surface of the Earth but only that accelerometer hardware 
is not always as precise as we’d prefer. 

Both the Y and Z components are negative, indicating that the tablet is tilted back somewhat. As 
I mentioned earlier, if the tablet is sitting straight up, the vector is theoretically ( 0 , 一 1 , 0 ), and if it's 
sitting on the desk with the screen pointing straight up, the vector is theoretically (0, 0, -1). Between 
those two positions, the tablet is being rotated around its X axis. Pass the Y and Z values to the 
Math.Aton2 method, and you’ll get that angle of rotation. 

If you run this program on a handheld device, you can twist the device around in different 
orientations to see the effect. Generally, you’ll see the following correspondence between the 
SimpleOrientotionSensor and the Accelerometer: 


SimpleOrientotionSensor 

Accelerometer Vector 

NotRotated 

〜 （ 0, - 1 , 0) 

Rototed90DegreesCounterClockwise 

~ (-1, 0, 0) 

Rototedl80DegreesCounterClockwise 

〜 （ 0, 1 , 0) 

Rototed270DegreesCounterClockwise 

〜 （ 1, 0, 0) 

Faceup 

〜 （ 0, 0, -1) 

Facedown 

- (0, 0, 1) 


That "approximately equal to" symbol ㈠ should be interpreted very liberally. The Accelerometer 
vectors obviously show quite a bit of variation before they reach a value that precipitates a change to 
SimpleOrientotionSensor. 
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This AccelerometerAndSimpleOrientation program doesn't indicate any preferred orientations, so 
as you’re moving the tablet around in space, Windows automatically changes the display orientation 
under the assumption that you don’t want to read numbers that are upside down. You should see a 
correspondence between the SimpleOrientationSensor values and the orientation of the screen, but 
this is only because Windows changes the display orientation based on these values! If you inhibit 
Windows from changing the screen orientation (by whatever means), the information displayed by 
this program is not affected. 

In fact, you might find the continual display orientation changes to be rather annoying. As each 
one occurs, the updating of the screen pauses for a moment and the contents contract to signal this 
change. Think about it for a little while, and you’ll probably come to the conclusion that programs 
that use the Accelerometer to alter screen content probably should also inhibit automatic display 
orientation changes. 

For this reason, all of the programs in the remainder of this chapter include a simple statement in 
the program’s constructor to set the preferred orientation to the native orientation: 

DisplayProperties .AutoRotationPreferences = DisplayProperties .NativeOrientation; 

You’ll discover that if you run the AccelerometerAndSimpleOrientation program on a handheld 
device and move it rapidly, the direction and magnitude of the acceleration vector also change to no 
longer indicate lg force coming from the center of the Earth. For example, if you jerk the device to 
the left, the acceleration vector points right — but only when the device is accelerating. If you manage 
to keep moving it at a steady velocity, the acceleration vector will settle down and resume pointing 
to the Earth. Suddenly stop the device from moving, and the acceleration vector also indicates that 
change in velocity. 

The Accelerometer class also defines an event named Shaken with no other information. This 
event is useful for a program that needs to "throw" a pair of dice, or propose another restaurant 
recommendation, or perhaps erase a drawing or undo an accidental erasure. 

One common application of an Accelerometer is a bubble level. This XAML file instantiates four 
Ellipse elements. Three are drawn as concentric outlines, and the fourth is the bubble itself: 


Project: BubbleLevel | File: MainPage.xaml (excerpt) 

<Grid Background:'' {StaticResource ApplicationPageBackgroundThemeBrush}"> 

<Grid Name="centeredGri d" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Center"> 

〈Ellipse Name="outerCi rcle" 

Stroke="{StaticResource ApplicationForegroundThemeBrush}" /> 
〈Ellipse Name="ha1fCi rcle" 

Stroke="{StaticResource ApplicationForegroundThemeBrush}" /> 

〈Ellipse Width="24" 

Height="24" 

Stroke="{StaticResource ApplicationForegroundThemeBrush}" /> 
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〈Ellipse Fin="Red" 
Width="24" 


Height="24" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Center"> 

<E11ipse.RenderTransform> 

<T ranslateTransform x : Name="bubbl eTranslate" /> 
</El1ipse.RenderTransform> 

</El1ipse> 

</Grid> 

</Grid> 


The code-behind file sets DisployProperties.AutoRototionPreferences to 
DisployProperties.NativeOrientotion. There is simply no reason for Windows to be 
automatically changing the display orientation of this program. The program also processes 
the SizeChanged handler to set the dimensions of outerCircle and half Circle: 


Project: BubbleLevel I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

Accelerometer accelerometer = Accel erometer.GetDefault(); 


public MainPageO 

{ 

this. Ini tializeComponent(); 

DisplayProperties .AutoRotationPreferences = DisplayProperties .NativeOrientation; 
Loaded += OnMainPageLoaded; 

SizeChanged += OnMainPageSizeChanged; 

} 

async void OnMai nPageLoaded (object sender, RoutedEventArgs args) 

{ 

if (accelerometer != null) 

{ 

accelerometer.Reportlnterval = accelerometer.MinimumReportlnterval; 

SetBubble(accelerometer.GetCurrentReadi ng()); 
accelerometer.ReadingChanged += OnAccelerometerReadingChanged; 

} 

else 

{ 

await new MessageDi alog("Accel erometer is not available") .ShowAsyncO; 

} 

} 

void OnMai nPageSi zeChanged(object sender, SizeChangedEventArgs args) 

{ 

double size = Math .Min(args.NewSize.Width, args.NewSize.Height); 

outerCircle.Width = size; 

outerCircle.Height = size; 

halfCircle.Width = size / 2; 

halfCircle.Height = size / 2; 
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async void OnAccelerometerReadingChanged(Accel erometer sender, 

AccelerometerReadingChangedEventArgs args) 

{ 

await this .Dispatcher.RunAsync(CoreDi spatcherPriority. Normal ,()=> 

{ 

SetBubble(args.Reach ng); 

}); 

} 

void SetBubbl e(Accel erometerReading accelerometerReading) 

{ 

if (accelerometerReading == null) 
return ; 

double x = accelerometerReading.AccelerationX; 
double y = accelerometerReading.AccelerationY; 

bubbleTranslate.X = -x * centeredGrid.ActualWidth / 2; 
bubbleTranslate.Y = y * centeredGrid.ActualHeight / 2; 



The SetBubble method looks too simple: It just takes the X and Y components of the acceleration 
vector and uses those to set the X and Y coordinates of that center bubble, scaled to the radius of the 
outer circle. But consider a tablet sitting face up or face down on a table. The Z component of the 
acceleration vector is 1 or -1, and the X and Y components are both zero, meaning the bubble sits in 
the center of the screen. That’s correct. 

Now hold the tablet so that the screen is perpendicular to the Earth. The Z component becomes 
zero. This means that the magnitude of the acceleration vector results entirely from the X and Y 
components. In other words: 

2,2 i2 

X + 少 =1 

That’s the equation for a circle in two dimensions, so the bubble sits somewhere on that outer circle. 
Where exactly it sits is based on the current rotation of the tablet around its Z axis. 

The acceleration vector points down toward the center of the Earth, and bubbles travel up, which 
means we need to swap the signs of the X and Y components of the acceleration vector to convert to 
two-dimensional screen coordinates. But recall that the Y axis of the acceleration vector is reversed 
from screen coordinates anyway, so only the X component needs to have its sign swapped, as you can 
see in the last two lines of code in the program. 
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Here’s the program running on a Microsoft Surface tablet: 



Of course, this screen shot doesn’t quite capture how jittery the bubble is in real life. The 
Accelerometer values are rather raw, and in a real-life application you’ll want to smooth them out a 
bit. I do this in the next two programs. 

Follow the Rolling Ball 

Using the Accelerometer is common in games for handheld devices. For example, if you have a game 
that simulates the driving of a car, the user might steer the car by tilting the computer to the left or 
right. 

The following two programs simulate a ball rolling around the screen. If you hold the screen of 
your tablet parallel to the Earth and balance a real ball on top, you can make that ball roll around by 
tilting the screen. The greater the tilt, the greater the acceleration of the ball. The virtual ball in the 
next two programs moves in a similar way. Like the bubble level program, these programs ignore 
the Z component of the Accelerometer vector and use only the X and Y components to govern 
acceleration on the two-dimensional surface of the screen. 


In the TiltAndRoll program, when the ball strikes one of the edges, it loses all its velocity in the 
direction perpendicular to the edge, continuing to roll along the edge if it still has velocity in that 
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direction. The XAML file defines the ball. An EllipseGeometry allows the ball to be positioned at a 
particular coordinate by setting the Center property: 


Project: TiltAndRoll I File: MainPage.xaml (excerpt) 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Path Fill= ,, Red"> 

<Path.Data> 

〈EllipseGeometry x:Name="ba11 " /> 

〈 /Path.Data 〉 

</Path> 

</Grid> 


The code-behind file begins by defining a constant for GRAVITY in units of pixels per second 
squared. Theoretically, a sliding ball without friction is subject to the full force of gravity, but the 
acceleration of a rolling ball is 2/3 of gravitational acceleration. (See A. P. French, Newtonian Mechan¬ 
ics, W. W. Norton, 1971, pages 652-3, for the gory details.) This means you can calculate a value for 
GRAVITY by multiplying 32 feet per second squared by 12 inches per foot and 96 pixels per inch and 
2/3 and get a value about 25,000, but I slowed it down considerably. 

A two-dimensional vector value is very useful in calculations involving two-dimensional 
acceleration, velocity, and position, so I included the Vector2 structure from Chapter 13, "Touch, Etc." 

Because the ball needs to keep rolling regardless of the firing of the ReadingChonged event 
of the Accelerometer, the program doesn’t install a handler for that event and instead uses 
CompositionTarget.Rendering to obtain the current value and apply it to the ball. Notice that the X 
and Y components of the Accelerometer readings are used to create a Vector2 value, which is then 
averaged with the previous value, which itself is an average of its previous value, and so forth. This is 
an extremely simple form of smoothing: 


Project: TiltAndRoll I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 
{ 

const double GRAVITY = 5000; // pixels per second squared 

const double BALL_RADIUS = 32; 


Accelerometer accelerometer = Accel erometer.GetDefault(); 

TimeSpan timeSpan; 

Vector2 acceleration; 

Vector2 ballPosition; 

Vector2 ballVelocity; 

public MainPage() 

{ 

this. InitializeComponent(); 

DisplayProperties .AutoRotationPreferences = DisplayProperties. NativeOrientation; 

ball.RadiusX = BALL_RADIUS; 
ball.RadiusY = BALL_RADIUS; 

Loaded += OnMainPageLoaded; 

} 
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async void OnMainPageLoaded (obj ect sender, RoutedEventArgs args) 


if (accelerometer == null) 

{ 

await new MessageDial og("Accelerometer is not available") .ShowAsyncO; 

} 

else 

{ 

CompositionTarget .Rendering += OnComposi tionTargetRendering; 

} 

} 


void OnCompositionTargetRenderi ng(object sender, object args) 

{ 

AccelerometerReach ng reading = accelerometer.GetCurrentReading(); 

if (reachng == null) 
return ; 

// Get elapsed time si nee last event 

TimeSpan timeSpan = (args as RenderingEventArgs) .RenderingTime; 
double elapsedSeconds = (timeSpan - this .timeSpan).TotalSeconds; 
this .timeSpan = timeSpan; 

// Convert accelerometer reading to display coordinates 
double x = reading.AccelerationX; 
double y = -reading.AccelerationY; 

// Get current X-Y acceleration and smooth it 
acceleration = 0.5 * (acceleration + new Vector2(x, y)); 


// Calculate new velocity and position 

ballVelocity += GRAVITY * acceleration * elapsedSeconds; 

ballPosition += ballVelocity * elapsedSeconds; 


// Check for hitting edge 
if (ballPosition_X - BALL_RADIUS < 0) 
{ 


if 


{ 



if 


ball Position = 
ballVelocity = 

(ballPosition.X 

ball Position = 
ballVelocity = 

(ballPosition.Y 


new Vector2 (BALL_RADIUS, bal1Position.Y); 
new Vector2(0, ballVelocity.Y); 

+ BALL_RADIUS > this .ActualWidth) 

new Vector2 (this. ActualWidth - BALL_RADIUS, 
new Vector2(0, ballVelocity.Y); 

- BALL_RADIUS < 0) 


ballPosition.Y); 


ball Position = new Vector2 (bal1 Position.X, BALL—RADIUS); 
ballVelocity = new Vector2CballVelocity.X, 0); 

} 

if (bal1Position.Y + BALL_RADIUS > this .ActualHeight) 


bal1Position = new Vector2 (ballPosition.X, this .ActualHeight - 
ballVelocity = new Vector2(ballVelocity.X, 0); 

} 

bal 1 .Center = new Poi nt(bal1Position.X, ballPosition.Y); 


BALL_RADIUS); 


} 


} 
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The two crucial calculations are these: 

balIVelocity += GRAVITY * acceleration * elapsedSeconds; 
ballPosition += ball Velocity * elapsedSeconds; 

Keep in mind that acceleration, bo 11 Velocity, and bollPosition are all Vector2 values, so they all have X 
and Y components. The velocity is increased by the acceleration times elapsed time, and the posi¬ 
tion is increased by the velocity times elapsed time. Then it’s only a matter of checking whether the 
new position is outside the bounds of the page. If so, it’s moved back within the page and one of the 
components of the velocity is set to zero. 

The physics are fairly realistic. As you increase and decrease the tilt, the magnitude of the 
acceleration of the ball increases and decreases. Moreover, because the program is dealing with 
actual formulas for velocity and position, it becomes fairly easy to add some bounce. One easy way 
is to not set the velocity component to zero when the ball hits the edge but to make that velocity 
component the negative of its previous value. However, that means the ball has the same velocity 
magnitude after the bounce, and that’s unrealistic. It makes more sense to include an attenuation 
factor that I called BOUNCE. Everything in this TiltAndBounce program is the same as TiltAndRoll 
except for that BOUNCE constant and different ball-moving logic in the CompositionTorget.Rendering 
handler: 


Project: TiltAndBounce I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 


const double BOUNCE = -2.0 / 3; // fraction of velocity 

void OnCompositionTargetRenderi ngCobject sender, object args) 

{ 

AccelerometerReading reading = accelerometer.GetCurrentReading(); 

if (reading == null) 
return ; 

// Get elapsed time 

TimeSpan timeSpan = (args as RenderingEventArgs). RenderingTime; 
double elapsedSeconds = (timeSpan - this .timeSpan).TotalSeconds; 
this .timeSpan = timeSpan; 


// Convert accelerometer reading to display coordinates 
double x = reading.AccelerationX; 
double y = -reading.AccelerationY; 

// Get current X-Y acceleration and smooth it 
acceleration = 0.5 * (acceleration + new Vector2(x, y)); 

// Calculate new velocity and position 

balIVelocity += GRAVITY * acceleration * elapsedSeconds; 

bal1Position += ball Velocity * elapsedSeconds; 


// Check for bouncing off edge 
bool needAnotherLoop = true; 
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while (needAnotherLoop) 

{ 

needAnotherLoop = false; 


if (bal1Position.X - BALL_RADIUS < 0) 

{ 

ball Position = new Vector2 (-ballPosition.X + 2 * BALL_RADIUS, bal1Position.Y); 
ballVelocity = new Vector2 (BOUNCE * bal1Velocity.X, ballVelocity.Y); 
needAnotherLoop = true; 

} 

else if (bal1Position.X + BALL_RADIUS > this _ActualWidth) 

{ 

ball Posi tion = new Vector2(-ballPosition.X + 2 * 

(this .ActualWidth - BALL_RADIUS ) ， 

bal 1Position. Y); 

ballVelocity = new Vector2 (BOUNCE * ballVelocity.X, ballVelocity.Y); 
needAnotherLoop = true; 

} 

else if (bal1Position.Y - BALL_RADIUS < 0) 

{ 

ballPosition = new Vector2 (ballPosition.X, -bal1Position.Y + 2 * BALL_RADIUS); 
ballVelocity = new Vector2(ballVelocity.X, BOUNCE * ballVelocity.Y); 
needAnotherLoop = true; 

} 

else if (bal1Position.Y + BALL_RADIUS > this .ActualHeight) 

{ 

bal1Position = new Vector2 (bal1Position.X, 

-bal1Position.Y + 2 * 

(this .ActualHeight - BALL—RADIUS)); 
ballVelocity = new Vector2 (ballVelocity.X, BOUNCE * ballVelocity.Y); 
needAnotherLoop = true; 

} 

} 

bal 1 .Center = new Poi nt(bal1Position.X, ballPosition.Y); 

} 

} 


In the TiltAndRoll program, it was possible for the ball to go beyond two adjacent edges during 
the same event, but those cases were handled with a series of //statements. In this program, bouncing 
the ball off one edge could make it go beyond another edge, which means that a loop is necessary to 
test the position of the ball repeatedly until there are no more bounces. 


The Two Norths 


Although the Accelerometer tells you which way is down, it doesn’t reveal the complete orientation of 
the device in 3D space. To see what I mean, run the AccelerometerAndSimpleOrientation program on 
a handheld device. Stand up, and hold the device in some odd configuration. The Accelerometer tells 
you which way is down. Now turn your whole body around in a circle. The tablet has rotated 360 de¬ 
grees in space, but the Accelerometer has reported pretty much the same value because the direction 
of down has remained the same relative to the device. 
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When you turn the tablet in a circle around the acceleration vector, what changes? One answer 
is: The direction of north relative to the tablet. This is why a Compass sensor is so important: It 
provides a missing factor in determining the tablet’s orientation. By combining the Compass and 
the Accelerometer, you can derive a complete orientation of the tablet in 3D space. Or you can let 
Windows do it for you. 

The Compass class is structured much like Accelerometer, and the CompossReoding class has two 
properties: HeadingMagneticNorth and HeodingTrueNorth. These are both angles in degrees, and 
they indicate the angle of the computer relative to north. The angles should be close to zero if you 
hold your tablet screen parallel to the Earth and point the top of the screen toward north. (By "top” 
I’m referring to the direction of the positive Y axis in the diagrams shown earlier in this chapter.) As 
you turn the tablet screen toward the east, the angles increase. 

Of course, these angles shouldn’t be the same except in certain locations around the world. 

The tablet contains a magnetometer that responds to magnetic north (which is aligned with the 
Earth’s magnetic field); true north refers to the axis around which the Earth rotates. Interestingly, the 
HeadingMagneticNorth property is of type double, but HeodingTrueNorth is of type nullable double, 
which ominously suggests that the value might not be available. 

Let’s try it. The XAML file for the SimpleCompass project defines two graphical arrows that have 
origins in the center of the screen and point straight up: 


Project: SimpleCompass | File: MainPage.xaml (excerpt) 

<Crid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Canvas HorizontalA1i gnment="Center" 

VerticalAli gnment="Center"> 

<Path Fi1 l="Magenta" 

Data="M -10 0 L 10 0 ， 10 -300 ， 0 -350 ， -10 -300 Z"> 

<Path.RenderTransform> 

<RotateTransform x : Name="magNorthRotate" /> 

</Path.RenderTransform> 

</Path> 

<Path Name="trueNorthPath" 

Fill="Blue" 

Data="M -10 0 L 10 0, 10 -BOO, 0 -350, -10 -300 Z"> 

<Path.RenderTransform> 

<RotateTransform x: Name="trueNorthRotate" /> 

</Path.RenderTransform> 

</Path> 

</Canvas> 

</Crid> 


The two mnemonic colors are Magenta for Magnetic north and Blue for True north. 
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The code-behind file hides the second Path if the value of HeodingTrueNorth is null: 


Project: SimpleCompass | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

Compass compass = Compass .GetDefault(); 

public MainPage() 

{ 

this. Ini tializeComponent(); 

DisplayProperties .AutoRotationPreferences = DisplayProperties .NativeOrientation; 
Loaded += OnMainPageLoaded; 

} 

async void OnMainPageLoaded (object sender, RoutedEventArgs args) 

{ 

if (compass != null) 

{ 

ShowCompassValues(compass.GetCurrentReadi ng()); 
compass.Reportlnterval = compass.MinimumReportlnterval; 
compass.ReadingChanged += OnCompassReadingChanged; 

} 

else 

{ 

await new MessageDialog ("Compass is not available") .ShowAsyncC); 

} 

} 

async void OnCompassReadingChanged (Compass sender, CompassReadingChangedEventArgs args) 

{ 

await this .Dispatcher.RunAsync(CoreDi spatcherPriority .Normal,()=> 

{ 

ShowCompassValues(args■Readi ng); 

})； 

} 

void ShowCompassValues (CompassReading compassReading) 

{ 

if (compassReading == null) 
return ; 

magNorthRotate.Angle = -compassReading.HeadingMagneti cNorth; 

if (compassReading.HeadingTrueNorth.HasValue) 

{ 

trueNorthPath.Vi sibi1ity = Vi sibi1ity. Vi sible; 
trueNorthRotate.Angle = -compassReading.HeadingTrueNorth.Value; 

} 

else 

{ 

trueNorthPath.Vi sibi1ity = Visibility .Collapsed; 

} 
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Notice that the rotation angles of the two arrows are set to the negatives of the 
HeadingMagneticNorth and HeodingTrueNorth properties. These values indicate the rotation of the 
computer relative to north, so the arrows need to be rotated oppositely and show the direction of 
north relative to the computer. 

On both tablets I’ve been using for this book — including a Microsoft Surface machine — the results 
are disappointing. The HeodingTrueNorth value is always null on both machines. On the Microsoft 
Surface, the value for magnetic north is quite erratic. On the Samsung tablet, values only range from 
0 to 180 degrees! On my Technical Editor’s tablet, HeodingMogneticNorth is always 0. 

In theory, true north can be calculated from magnetic north knowing the location of the computer, 
but enabling Location capabilities in Package.appxmanifest doesn't help. 

Nevertheless, we can cross our fingers and hope that the compass hardware works sufficiently well 
to be combined with accelerometer data and provide complete orientation information. 

Inclinometer = Accelerometer + Compass 

The Inclinometer sensor is one of two classes that internally combines accelerometer and compass 
data and smooths the result somewhat. This class provides information in the form of yaw, pitch, and 
roll angles, which are terms used in flight dynamics. 

The yaw, pitch, and roll angles are often referred to as Euler angles, after 18 th -century 
mathematician Leonhard Euler, who explored the mathematics of three-dimensional rotation. If you’re 
flying a plane, yaw indicates the compass direction that the nose of the plane is facing. As the plane 
veers left or right, the yaw changes. Pitch indicates the angle of the nose of the plane. As the nose 
goes up for a climb and down for a dive, the pitch changes. Roll is achieved by banking left or right. 

To understand how these apply to the computer, you might want to visualize yourself "flying" 
your tablet like a magic carpet. Assume a sitting position on the screen facing toward the top (in 
the tablet’s native orientation, of course) and take off. In the coordinate system shown earlier in this 
chapter, yaw is rotation around the Z axis, pitch is rotation around the X axis, and roll is rotation 
around the Y axis. 

The YawPitchRoll program also helps you visualize these angles. The XAML file contains some 
Rectangle elements used for lines, some Ellipse elements used as rolling balls, and some text: 

Project: YawPitchRoll I File: MainPage.xaml (excerpt) 

<Grid Background=" {StaticResource ApplicationPageBackgroundThemeBrush}"> 

<!-- Pitch --> 

<Rectangle Fi1 1="B1 ue" 

Width="3" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Stretch" /> 

<Path Name="pi tchPath" 

Stroke="Bl ue"> 

<Path.Data> 
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<E11ipseGeometry x : Name="pi tchEl1ipse" Radi usX="20" RadiusY="20" /> 
</Path.Data> 

</Path> 


<!-- Roll --> 

〈Rectangle Fi1 l="Red" 

Height="3" 

HorizontalAli gnment="Stretch" 

VerticalAli gnment="Center" /> 

〈Path Name="rol 1 Path" 

Stroke="Red" 

Fill="Red n > 

〈 Path.Data 〉 

<E11ipseGeometry x : Name=" rol1 El 1ipse" Radi usX="20" Radi usY="20" /> 
〈 /Path•Data> 

</Path> 


<Gri d> 

<Grid.RowDefinitions> 

〈RowDefinition Height:"*" /> 
〈RowDefinition Height:"*" /> 

</Grid.RowDefinitions> 

<Grid.ColumnDefinitions> 

<ColumnDefinition Width="*" /> 

<ColumnDefinition Width="*" /> 

</Grid.ColumnDefiniti ons> 

<!-- Pitch --> 

〈TextBlock Text=" PITCH" 

Gn'd.Row= M 0" 

Grid.Col umn="0" 
Foreground="Bl ue" 

HorizontalAli gnment="Ri ght" 
Margin="0 0 24 0" /> 

<TextBlock Name="pi tchValue" 
Gn'd.Row= M 0" 

Grid.Col umn="l" 
Foreground="Bl ue" 

HorizontalAli gnment="Left" 
Margin="24 0 0 0" /> 

<!-- Roll --> 

<TextBlock Text="R0LL" 

Grid.Row="l n 
Grid.Col umn="0 M 
Foreground:" Red" 

HorizontalAli gnment="Left" 
VerticalAli gnment="Top" 
Margin="0 108 0 0"> 
<TextBlock.RenderTransform> 

<RotateTransform Angle="-90" /> 
</TextBlock.RenderTransform> 
</TextBlock> 
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<TextBlock Name=" rollValue" 

Grid.Row= M 0" 

Grid.Col umn="0" 
Foreground="Red" 

HorizontalAli gnment="Left" 
VerticalA1i gnment="Bottom"> 
<TextBlock.RenderTransform> 

<RotateTransform Angle="-90" /> 
</TextBlock.RenderTransform> 
</TextBlock> 


<!-- Yaw --> 

〈Grid Grid. Row="0" 

Grid.Col umn="l" 

HorizontalAli gnment="Stretch" 

VerticalA1i gnment="Bottom" 

RenderT ransformOrigi n="0 1"> 

<StackPanel Orientati on="Hori zontal" 

HorizontalAli gnment="Center"> 

〈TextBlock Text="YAW = " Foreground="Green" /> 
<TextBlock Name= n yawVa"l ue” Foreground="Green" /> 
</StackPanel> 

<Rectangle Fi1 l="Green" 

Height="B" 

HorizontalAli gnment="Stretch" 

VerticalA1i gnment="Bottom" /> 


<Grid.RenderTransform> 

<TransformGroup> 

<RotateTransform Angle="-90" /> 
<RotateTransform x : Name="yawRotate" /> 
</TransformGroup> 

</Grid.RenderTransform> 

</Grid> 

</Grid> 

</Crid> 


As you can see from the code-behind file, the Inclinometer class is instantiated and used much like 
Accelerometer and Compass.. 


Project: YawPitchRoll I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

Inclinometer inclinometer = Incli nometer.GetDefault(); 

public MainPageO 

{ 

this. InitializeComponent(); 

DisplayProperties .AutoRotationPreferences = DisplayProperties. NativeOrientation; 
Loaded += OnMainPageLoaded; 

} 

async void OnMainPageLoaded (object sender, RoutedEventArgs args) 
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if (inclinometer == null) 

{ 

await new MessageDi alog("Cannot obtain Inclinometer") .ShowAsyncO; 
} 一 
else 

{ 

ShowYawPitchRol1(inclinometer.GetCurrentReach ng()); 
inclinometer.Reportlnterval = inclinometer.MinimumReportlnterval; 
inclinometer.ReadingChanged += OnlnclinometerReadingChanged; 

} 


async void OnlnclinometerReadingChanged(Incl inometer sender, 

InclinometerReadingChangedEventArgs args) 

{ 

await this. Dispatcher.RunAsync(CoreDi spatcherPriority .Normal,()=> 

{ 

ShowYawPitchRol1(args■Reading); 

}); 


void ShowYawPitchRol1 (InclinometerReading inclinometerReading) 

{ 

if (inclinometerReading == null) 
return ; 

double yaw = inclinometerReading.YawDegrees; 
double pitch = inclinometerReading.PitchDegrees; 
double roll = inclinometerReading.Rol1 Degrees; 

yawValue.Text = yaw.ToStri ng("F0") + " 0 " ; 
pitchValue.Text = pitch.ToStri ng("F0 ”） + "° ; 
rollValue.Text = roll.ToStri ng("F0") + "° ; 

yawRotate.Angle = yaw; 

if (pitch <= 90 && pitch >= -90) 

{ 

pitchPath.Fi11 = pitchPath.Stroke; 

pitchEllipse.Center = new Poi nt(thi s .ActualWidth / 2 ， 

this. Actual Height * (pitch + 90) / 180); 

} 

else 

{ 

pitchPath.Fi11 = null; 
if (pitch > 90) 

pitchEl1ipse.Center = new Poi nt(thi s .ActualWidth / 2, 

this.ActualHeight * (270 - pitch) / 180); 

else // pitch < -90 

pitchEl1ipse.Center = new Poi nt(thi s .ActualWidth / 2, 

this.ActualHeight * (-90 - pitch) / 180); 

} 

roll Ell ipse.Center = new Point (thi s .ActualWidth * (roll + 90) / 180, 



} 
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There’s no secret source of compass data providing information for the Inclinometer. The 
YawDegrees property is just as erratic (or limited) as the Compass reading, except that they're 
complements: The sum of the YawDegrees and the Compass reading always approximately equals 
360. When the tablet is lying with its screen up on a level surface, the yaw line points toward north (or 
thereabouts) and the balls for pitch and roll both sit in the center. As you tilt the top of the tablet up 
or down, Pitch Degrees ranges from 90 degrees when the tablet is upright to -90 when the top of the 
tablet points down. RollDegrees ranges from 90 degrees to -90 degrees as the tablet is tilted right or 
left. Here’s a view when the top and left sides of the tablet are elevated: 

PITCH 28° 



When the screen faces down, YawDegrees points south, and PitchDegrees takes on values ranging 
from 90 degrees to 180 degrees, and from -90 degrees to -180 degrees. The program symbolizes 
these values with a hollow red ball. 

If you’re working with a program where something is flying around the screen, these Euler angles 
might be exactly what you need. However, you might want something more mathematically oriented. 
That’s the purpose of the next class. 

OrientationSensor = Accelerometer + Compass 

You can represent rotation in three-dimensional space several ways, all of which can be converted 
among each other. The OrientationSensor class is very similar to Inclinometer in the sense that it 
combines information from the accelerometer and compass to provide a complete orientation in 3D 
space. OrientationSensor provides this orientation in instances of two classes: 

■ SensorQuoternion 

■ SensorRototion Matrix 









1100 : 
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Quaternions are mathematically quite interesting. Just as an imaginary number can represent 
a rotation in two-dimensional space, a quaternion represents rotation in three-dimensional space. 
Game programmers particularly like representing rotations as quaternions because quaternions 
can be smoothly interpolated. (I discuss quaternions in Chapter 8 of my book 3D Programming for 
Windows [Microsoft Press, 2007].) 


A rotation matrix is a regular transform matrix missing the last row and last column. A regular 
three-dimensional transform matrix has 4 rows and 4 columns. The SensorRototionMotrix class defines 
3 rows and 3 columns. Such a matrix is incapable of representing translation or perspective, and by 
convention it incorporates no scaling or skew. But it can easily be used to rotate objects in 3D space. 


On the Samsung tablet I’m using to write this book, the SensorRotationMatrix contains all zeroes, 
so none of the programs in this book that use that matrix will work. Better results are available on the 
Microsoft Surface. 

When you're working with this rotation matrix, a change in perspective might be helpful. I’ve been 
describing how the values from the Accelerometer and Compass are relative to the 3D coordinate 
system I presented in the early pages of this chapter. When working with the rotation matrix from the 
OrientationSensor class, it helps to visualize two 3D coordinate systems, one for the device and the 
other for the Earth: 

■ In the computer’s 3D coordinate system, positive Y points to the top of the screen, positive X 
points to the right, and positive Z comes out of the screen, just as I showed earlier. 

■ In the Earth’s coordinate system, positive Y points north, positive X points east, and positive Z 
comes out of the ground. 

These two coordinate systems are aligned when the computer is lying on a level surface with its 
screen pointing up and the top pointing north. The SensorRotationMatrix becomes (theoretically) the 
identity matrix: Is in the diagonal and Os otherwise. Otherwise, the matrix describes how the Earth 
is rotated relative to the computer, which is the opposite of the rotation described by the Euler angles. 

This difference is demonstrated by the AxisAngleRotation program, which computes yet another 
method of representing rotation in three-dimensional space — as a rotation around a 3D vector. The 
XAML file is a not-very-interesting assemblage of Text Block elements, some functioning as labels and 
the others awaiting text: 


Project: AxisAngleRotation I File: MainPage.xaml (excerpt) 

<Page … > 

<Page.Resources 〉 

<Style x: Key="Defaul tTextBlockStyle" TargetType="TextBl ock"> 

〈Setter Property="FontFami ly" Val ue="Luci da Sans Uni code" /> 
〈Setter Property="FontSi ze" Value="36" /> 

〈Setter Property="Margi n" Value="0 0 48 0" /> 

</Style> 


〈Style x : Key=" rightText" Ta rgetType="Text Block" 

BasedOn="{Stati 〔Resource DefaultTextBlockStyl e}"> 
〈Setter Property="TextAl ignment" Val ue="Right" /> 
〈Setter Property="Margi n" Value="48 0 0 0" /> 
</Style> 

</Page.Resources> 
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<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<StackPanel HorizontalAli gnment="Center" 

VerticalAli gnment="Center"> 

<!-- Grid showing Pitch, Roll, and Yaw --> 

<Grid HorizontalAli gnment="Center"> 

<Grid.RowDefinitions> 

<RowDefinition Height="Auto" /> 

〈RowDefinition Height="Auto" /> 

〈RowDefinition Height="Auto" /> 

</Grid.RowDefinitions> 


<Grid.ColumnDefinitions> 

<ColumnDefinition Wi dth="Auto" /> 
<ColumnDefinition Wi dth="Auto" /> 
</Grid.ColumnDefinitions> 


<Grid.Resources> 

〈Style TargetType="TextBl ock" 

BasedOn="{Stati cResource DefaultTextBlockStyle}" /> 
</Grid.Resources 〉 

<TextBlock Text="Pitch: " Grid. Row="0" Grid.Col umn="0" /> 
<TextBlock Name="pi tchText" Grid. Row="0" Grid.Col umn="l" 

Styl e="{StaticResource rightText}" /> 

<TextBlock Text="Roll: " Grid.Row="l" Grid.Col umn="0" /> 
〈TextBlock Name="rol IText" Grid. Row="l" Grid.Column="l" 

Styl e="{StaticResource rightText}" /> 

〈TextBlock Text="Yaw: " Grid. Row="2" Grid.Col umn="0" /> 
〈TextBlock Name="yawText" Grid. Row="2" Grid.Column="l" 

Styl e="{StaticResource rightText}" /> 

</Gri d> 


<!-- Grid for RotationMatrix --> 

<Grid HorizontalAli gnment="Center" 

Margin="0 48"> 

<Grid.RowDefinitions> 

<RowDefinition Hei ght="Auto" /> 

<RowDefinition Hei ght="Auto" /> 

〈RowDefinition Height="Auto" /> 

</Grid.RowDefinitions> 

<Grid.ColumnDefinitions> 

<ColumnDefinition Wi dth="Auto" /> 

<ColumnDefinition Wi dth="Auto" /> 

<ColumnDefinition Wi dth="Auto" /> 

</Grid.ColumnDefinitions> 

<Grid.Resources 〉 

〈Style TargetType="TextBl ock" BasedOn="{Stati cResource rightText}" /> 
</Grid.Resources 〉 

〈TextBlock Name="mllText" Grid. Row="0" Grid.Col umn="0" /> 

<TextBlock Name="ml2Text" Grid. Row="0" Grid.Column="l" /> 

<TextBlock Name="ml3Text" Grid. Row="0" Grid.Column="2" /> 
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〈TextBlock Name="m21Text" 
〈TextBlock Name="m22Text" 
〈TextBlock Name="m23Text" 


Grid. Row="l" Grid.Col umn="0" 
Grid. Row="l" Grid.Col umn="l" 
Grid. Row="l" Grid.Col umn="2" 


/> 

/> 

/> 


〈TextBlock Name="m31Text" Grid. Row="2" Grid.Col umn="0" /> 
<TextBlock Name="m32Text" Grid. Row="2" Grid.Col umn="l" /> 
<TextBlock Name="m33Text" Grid. Row="2" Grid.Column="2" /> 
</Grid> 

<!-- Axis/Angle rotation display --> 

<Grid HorizontalAli gnment="Center"> 

<Grid.RowDefinitions> 

<RowDefinition Hei ght="Auto" /> 

〈RowDefinition Hei ght="Auto" /> 

</Grid.RowDefinitions> 


<Grid.ColumnDefini ti ons> 

<ColumnDefinition Wi dth="Auto" /> 
<ColumnDefinition Wi dth="Auto" /> 
</Crid.ColumnDefini ti ons> 


<Grid.Resources 〉 

〈Style TargetType="TextBl ock" 

BasedOn="{Stati 〔Resource DefaultTextBlockStyle}" /> 
</Crid.Resources 〉 


<TextBlock Text="Angl e : " Grid.Row="0" Grid.Col umn="0" /> 
〈TextBlock Name="angl eText" Grid. Row="0" Grid.Col umn="l" 
TextAli gnment="Center"/> 

<TextBlock Text="Axi s : " Grid. Row="l" Grid.Col umn="0" /> 
<TextBlock Name="axi sText" Grid. Row="l" Grid.Col umn="l" 
TextAli gnment="Center" /> 

</Gri d> 

</StackPanel> 

</Grid> 

</Page> 


The code-behind file instantiates both an Inclinometer to obtain the yaw, pitch, and roll angles, 
and an OrientationSensor to obtain (and display) the rotation matrix and convert it to an axis/angle 
rotation: 


Project: AxisAngleRotation I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

Inclinometer inclinometer = Inclinometer.GetDefaultC) ; 
OrientationSensor orientationSensor = OrientationSensor .GetDefault(); 


public MainPage() 

{ 

this .InitializeComponent(); 

DisplayProperties .AutoRotationPreferences = Displ ayProperties .NativeOrientati on; 
Loaded += OnMainPageLoaded; 
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async void OnMainPageLoaded (object sender, RoutedEventArgs args) 

{ 

if (inclinometer == null) 

{ 

await new MessageDial og("Inclinometer is not available") .ShowAsyncC); 

} 

else 

{ 

// Start the Inclinometer events 

ShowYawPitchRol1(inclinometer.GetCurrentReach ng()); 
inclinometer.ReadingChanged += OnlnclinometerReadingChanged; 

} 

if (orientationSensor == null) 

{ 

await new MessageDialog ("OrientationSensor is not available") .ShowAsyncC); 

} 

else 

{ 

// Start the OrientationSensor events 

ShowOrientation(orientationSensor.GetCurrentReading()); 

orientationSensor.ReadingChanged += OrientationSensorChanged; 

} 

} 

async void OnlnclinometerReadingChanged(Incl inometer sender, 

InclinometerReadingChangedEventArgs args) 

{ 

await this .Dispatcher.RunAsync(CoreDi spatcherPriority. Normal,()=> 

{ 

ShowYawPitchRol1(args■Reading); 

}); 

} 

void ShowYawPitchRol1 (InclinometerReading inclinometerReading) 

{ 

if (incl i nometerReading == null) 
return ; 

yawText.Text = inclinometerReading.YawDegrees.ToStri ng("F0") + "° ; 
pitchText.Text = inclinometerReading.PitchDegrees.ToStri ng("F0") + "° ; 
rollText.Text = inclinometerReading.Rol1 Degrees.ToStri ng("F0") + "° ; 

} 

async void OrientationSensorChanged (OrientationSensor sender, 

OrientationSensorReadingChangedEventArgs args) 

{ 

await this .Dispatcher.RunAsync(CoreDi spatcherPriority. Normal,()=> 

{ 

ShowOrientation(args.Readi ng); 

}); 

} 

void ShowOrientation (OrientationSensorReading orientationReading) 

{ 

if (orientationReading == null) 
return ; 
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SensorRotationMatrix matrix = orientationReading.RotationMatrix; 


if (matrix == null) 
return ; 


mllText.Text = matrix.Mll.ToString("F3"); 
ml2Text.Text = matrix.M12.ToString("F3") : 
ml3Text.Text = matrix.MlB.ToString("F3"); 


m21Text.Text = matrix.M21.ToStri ng("F3") ; 
m22Text.Text = matrix.M22.ToStri ng("F3") ; 
m23Text.Text = matrix.M2B.ToStri ng("F3") ; 


m31Text.Text = matrix.M31.ToStri ng("F3") ; 
m32Text.Text = matrix.M32.ToStri ng("F3") ; 
m33Text.Text = matrix.M33.ToStri ng("F3") ; 


// Convert rotation matrix to axis and angle 

double angle = Math. Acos((matrix.Mil + matrix.M22 + matrix.M33 - 1) / 2); 
angleText.Text = (180 * angle / Math .PI).ToStri ng("F0") ; 

if (angle != 0) 

{ 

double twoSine = 2 * Math .Sin(angle); 
double x = (matrix.M2B - matrix.M32) / twoSine; 

double y = (matrix.M31 - matrix.M13) / twoSine; 

double z = (matrix.M12 - matrix.M21) / twoSine; 


} 


axisText.Text = String. Format ("({0:F2} {1:F2} {2:F2 })"， x ， y ， z); 


Here’s a screen shot from the Microsoft Surface showing the three Euler angles at the top, the 
rotation matrix in the middle, and a derived axis/angle rotation at the bottom: 


Pitch: 

46° 


Roll: 

-5° 


Yaw: 

2 。 


0.997 - 

-0.017 

-0.074 

-0.042 

0.696 

-0.717 

0.063 

0.718 

0.693 

Angle: 

46 


Axis: (-1.00 0.10 0.02) 
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For this screen shot, I’m holding the tablet roughly toward north so that the yaw angle is nearly 
zero. The tablet is tilted a tiny bit to the left, and that makes the roll angle a bit negative. But I have 
elevated the top of the tablet by a whopping 46 degrees. That same angle is displayed at the bottom 
as derived from the rotation matrix. But look at the axis: That’s very nearly the vector (一 1, 0, 0), which 
is the negative X axis. Using the right-hand rule, point your thumb in the direction of the negative X 
axis. The curl of your fingers indicates the direction for rotations of positive angles (which this is), so it 
confirms what I said: The rotation matrix describes a rotation of the Earth relative to the computer. 

This means that if you want a rotation matrix that represents a rotation of the computer relative to 
the Earth, you need to invert the matrix. The SensorRototionMatrix class has no facility to invert itself, 
but the Matrix 3D structure does. (You’ll recall that Motrix3D is defined in the Windows. Ul.Xoml.Medio 
.Medio 3D namespace and used in connection with Matrix3D Project ion.) It’s a simple matter to create 
a Motrix3D value from a SensorRototion Matrix object and then invert it. 

I’m going to use that technique to create yet another representation of an orientation in 3D space. 


Azimuth and Altitude 


Conceptually, we live inside a celestial sphere. If you need to describe a location of an object in 3D 
space relative to yourself where distance doesn’t matter, points relative to this celestial sphere are 
very convenient. This celestial sphere is particularly suitable for programs that let you use a computer 
screen for viewing a world of virtual reality or augmented reality. In such programs you hold a tablet 
as if you’re using it to take a photograph from the camera on the back, but what you see on the 
screen is generated (in full or in part) by the program based on the screen’s orientation. By panning 
the screen in arcs, you can view different parts of this world. 

The celestial sphere has a familiar analogue in the terrestrial realm. When we need to identify a 
location on the Earth, we do so with longitude and latitude, both of which are angles with a vertex in 
the Earth’s center. Conceptually, we divide the Earth’s sphere in half at the equator. Lines of latitude 
are parallel to the equator and measured by positive angles north of the equator (to a maximum of 
90 degrees at the North Pole) and negative angles south of the equator (to -90 degrees at the South 
Pole). Angles of longitude are based on great circles that pass through these two poles measured 
from the Prime Meridian, which is the longitude line that passes through Greenwich, England. 

We can describe points on the celestial sphere in much the same way, but we’re at the center of 
the sphere looking out and the terminology is different. 

Point your outstretched arm in any direction. How can we identify that location? First, swing your 
arm up or down so that it becomes horizontal — that is, parallel to the surface of the Earth. The angle 
your arm has swung during this movement is called the altitude. 

Positive altitude values are above the horizon; negative values are below the horizon. Straight up is 
the zenith, an altitude of 90 degrees. Straight down is the nadir, an altitude of -90 degrees. 


You’re still pointing your outstretched arm toward the horizon, right? Now swing your arm so 
that it’s pointing north. The angle your arm has just swung this second time is called the azimuth. 
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Together, the altitude and azimuth constitute a horizontal coordinate, so named because the horizon 
divides the celestial sphere in half — similar to the equator in terrestrial coordinates. 

The horizontal coordinate has no information about distance. During a solar eclipse, the sun and 
moon have the same horizontal coordinate. The horizontal coordinate is not a location in 3D space; 
it’s a direction in 3D space from a viewer. In that sense the horizontal coordinate is like a 3D vector 
except that a vector is expressed in rectangular coordinates and the horizontal coordinate is spherical. 

To make the job of deriving a horizontal coordinate a little easier, let's first define a Vector3 
structure for encapsulating a 3D vector: 


Project: EarthlyDelights | File: Vector3.cs 

using System; 

using Windows■Foundation; 

using Windows.UI.Xaml.Media; 

using Windows■UI.Xaml.Media.Media3D; 


namespace Petzold.Windows8.VectorDrawing 
{ 

public struct VectorB 
{ 

// Constructors 

public Vector3 (double x, double y, double z) 
: this() 

{ 

X = x; 
y = y; 

Z = z; 

} 

// Properties 

public double X { private set; get; } 

public double Y { private set; get; } 

public double Z { private set; get; } 

public double LengthSquared 
{ 

get { return X * X + Y * Y + Z * Z; } 

} 


public double Length 
{ 

get { return Math .Sqrt(LengthSquared); } 

} 

public Vector3 Normalized 
{ 

get 

{ 

double length = this. Length; 
if (length != 0) 
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return new Vector3(thi s .X / length, 

this.Y / length, 
thi s.Z / length); 


return new Vector3() ; 

} 

} 

// Static properties 
public static Vector3 UnitX 
{ 

get { return new Vector3(l, 0, 0); } 

} 

public static Vector3 UnitY 

{ 

get { return new Vector3(0, 1, 0); } 

} 

public static Vector3 UnitZ 

{ 

get { return new Vector3(0, 0, 1); } 

} 

// Static methods 

public static Vector3 Cross(Vector3 vl, Vector3 v2) 

{ 

return new Vector3(vl.Y * v2.Z - vl.Z * v2.Y, 

vl.Z * v2.X - vl.X * v2.Z, 

vl.X * v2.Y - vl.Y * v2.X); 

} 


public static double Dot(Vector3 vl, Vector3 v2) 

{ 

return vl.X * v2.X + vl.Y * v2.Y + vl.Z * v2.Z; 

} 


public static double AngleBetween(Vector3 vl, Vector3 v2) 

{ 


} 


return 180 / Math. PI * Math .Acos(Vector3■ Dot(vl, v2) / 

vl.Length * v2.Length); 


public static Vector3 Transform(Vector3 v, Matrix3D m) 

{ 

double x = m.Mll * v.X + m.M21 * v.Y + m.M31 * v.Z + m.OffsetX; 

double y = m.M12 * v.X + m.M22 * v.Y + m.M32 * v.Z + m.OffsetY; 

double z = m.M13 * v.X + m.M23 * v.Y + m.M33 * v.Z + m.OffsetZ; 

double w = m.M14 * v.X + m.M24 * v.Y + m.M34 * v.Z + m.M44; 

return new Vector3(x / w, y / w, z / w); 

} 
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// Operators 

public static Vector3 operator +(Vector3 vl, Vector3 v2) 

{ 

return new Vector3(vl.X + v2.X, vl.Y + v2.Y, vl.Z + v2.Z); 

} 

public static Vector3 operator -(Vector3 vl, Vector3 v2) 

{ 

return new Vector3(vl.X - v2.X, vl.Y - v2.Y, vl.Z - v2.Z); 

} 

public static Vector3 operator * (Vector3 v, double d) 

{ 

return new Vector3(d * v.X, d * v.Y, d * v.Z); 

} 

public static Vector3 operator * (double d, Vector3 v) 

{ 

return new Vector3(d * v.X, d * v.Y, d * v.Z); 

} 

public static Vector3 operator /(Vector3 v, double d) 

{ 

return new Vector3(v.X / d, v.Y / d, v.Z / d); 

} 

public static Vector3 operator -(Vector3 v) 

{ 

return new Vector3(-v.X, -v.Y, -v.Z); 

} 

// Overrides 

public override string ToString() 

{ 

return String .Format ("({0} {1} {2})", X, Y, Z); 

} 



This structure has lots of goodies, including a traditional dot product and cross product, as well as 
a Transform method that multiplies the Vectors value by a Motrix3D value. In practice, this Motrix3D 
value probably represents a rotation, so the multiplication effectively rotates the vector in 3D space. 

When we hold our tablet up in the air and look at the screen, we are looking in a direction rela¬ 
tive to the computer’s coordinate system — specifically, in the direction of the vector coming out the 
back of the screen, which is the negative Z axis or (0, 0, -1). We need to convert that to a horizontal 
coordinate. 

Let's create a Matrix 3D value called matrix based on the SensorRotation Matrix object that 
OrientationSensor provides. That value can be inverted to represent a transform from the computer’s 
coordinate system to the Earth's coordinate system: 

matrix.Invert (); 
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Use that matrix to transform the (0,0, 一 1) vector (which is the negative of the static UnitZ property 
provided by the Vector3 structure) to Earth rectangular coordinates: 

Vector3 vector = Vector3 .Transform (-Vector3 .UnitZ, matrix); 

This vector is in rectangular coordinates, and we need to convert it to a horizontal coordinate. 
Recall that in the Earth’s coordinate system, the Z coordinate points out of the Earth, if the tablet is 
held upright, the axis coming from the back of the device transformed to Earth coordinates has a Z 
component of zero. This means that the azimuth can be calculated with the well-known conversion 
from two-dimensional Cartesian coordinates to polar coordinates, and let's convert it from radians to 
angles as well: 

double azimuth = 180 * Math .Atan2(vector.X, vector.Y) / Math. PI; 

That formula is actually valid regardless of the Z component of the transformed vector. Because 
the altitude ranges only between negative and positive 90 degrees, it can be calculated with the 
inverse sine function: 

double altitude = 180 * Math .Asin(vector.Z) / Math. PI; 

But we Ye missing something. We’ve converted a three-dimensional rotation matrix into a 
coordinate that has only two components because it’s confined to the interior surface of a sphere. 
What happens when you point your tablet at something on the celestial sphere and then rotate the 
tablet around that axis? It’s the same altitude and azimuth, but the view on the computer’s screen 
should definitely change through rotation. This missing component is sometimes called tilt. It’s a little 
more difficult to compute, but the math is shown in this HorizontalCoordinate structure: 

Project: EarthlyDelights I File: HorizontalCoordinate.es 

using System; 

using Windows.UI.Xaml.Media.Media3D; 

namespace Petzold.Windows8.VectorDrawing 

{ 

public struct HorizontalCoordinate 

{ 

public HorizontalCoordinate (double azimuth, double altitude, double tilt) 

: this() 

{ 

this. Azimuth = azimuth; 
this. Altitude = altitude; 
this. Tilt = tilt; 

} 

public HorizontalCoordi nate(doubl e azimuth, double altitude) 

: this (azimuth ， altitude, 0) 

{ 

} 
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// Eastward from north 

public double Azimuth { private set; get ; } 
public double Altitude { private set; get ; } 
public double Tilt { private set ; get; } 

public static HorizontalCoordinate FromVector(Vector3 vector) 

{ 

double altitude = 180 * Math. Asin(vector.Z) / Math. PI; 

double azimuth = 180 * Math .Atan2(vector.X, vector.Y) / Math .PI; 


return new HorizontalCoordinate (azimuth, altitude); 

} 

public static HorizontalCoordinate FromMotionMatrix(Matri x3D matrix) 

{ 

// Invert the matrix 
matrix.Invert(); 

// Transform (0, 0 ， -1) -- the vector extending from the lens 
Vector3 zAxisTransformed = Vector3 .Transform (-Vector3 .UnitZ, matrix); 


// Get the horizontal coordinates 

Horizontal Coordinate horzCoord = FromVector(zAxisTransformed); 


// Find the theoretical HorizontalCoordi nate for the transformed +Y vector 
// if the device is upright 
double yUprightAltitude = 0; 
double yUprightAzimuth = 0; 

if (horzCoord.Altitude > 0) 

{ 

yUprightAltitude = 90 - horzCoord.Altitude; 
yUprightAzimuth = 180 + horzCoord.Azimuth; 

} 

else 

{ 

yUprightAltitude = 90 + horzCoord.Altitude; 
yUprightAzimuth = horzCoord.Azimuth; 

} 

Vector3 yUprightVector = 

new HorizontalCoordinate (yUprightAzimuth, yUprightAltitude).ToVector(); 
// Find the real transformed +Y vector 

Vector3 yAxisTransformed = Vector3 .Transform (Vector3 .UnitY, matrix); 


// Get the angle between the upright +Y vector and the real transformed +Y vector 
double dotProduct = Vector3 .Dot(yUprightVector, yAxisTransformed); 

Vector3 crossProduct = Vector3 .Cross(yUprightVector, yAxisTransformed); 
crossProduct = crossProduct.Normalized; 
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// Sometimes dotProduct is slightly greater than 1 ， which 
// raises an exception in the angleBetween calculation, so ■… 
dotProduct = Math .Min(dotProduct, 1); 

double angleBetween = 180 * Vector3. Dot(zAxisTransformed, crossProduct) 

* Math. Acos(dotProduct) / Math .PI; 
horzCoord.Ti1t = angleBetween; 



return horzCoord; 


public Vector3 
{ 

double x = 
double y = 
double z = 


ToVectorO 

Math. Cos (Math. PI 
Math. Sin (Math. PI 
Math. Cos (Math. PI 
Math .Cos (Math .PI 
Math. Sin (Math. PI 


* this .Altitude / 180) * 

* this. Azimuth / 180); 

* this .Altitude / 180) * 

* this. Azimuth / 180); 

* this. Altitude / 180); 


return new Vector3((float)x , (float)y , (float)z) ; 

} 


} 


public override string ToString() 

{ 

return String. Format("Azi : {0} Alt: {1} Tilt: {2}" , 

this .Azimuth, this. Altitude, this. Tilt); 


} 


With this conversion, you’re well on your way to making an astronomy program that displays 
a particular segment of the night sky depending how you orient the screen, much like I did for 
Windows Phone 7.5 in the October 2012 issue of MSDN Magazine. But let’s do something here a bit 
less ambitious. 

What if you wanted to look at a bitmap that was much larger than the computer screen, and you 
didn’t want to shrink it to fit? One traditional solution involves scrollbars. A more modern solution 
allows you to move it around with your fingers. 

But another approach involves putting this bitmap on the interior of the celestial sphere. You 
can then view this image by holding the tablet aloft and changing the orientation of the screen. Of 
course, we don't want to actually stretch a bitmap so that it conforms to the interior of a sphere! 
Instead, we’ll simply use the azimuth for horizontal scrolling and the altitude for vertical scrolling. 
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The EarthlyDelights program lets you view a large (7,793 by 4,409 pixels) bitmap of Hieronymus 
Bosch’s 500-year-old painting, The Garden of Earthly Delights. The program downloads the image 
from Wikipedia. Here’s one part of it as displayed by the program running on Microsoft Surface: 



The program has no touch interface for scanning or zooming the image. Everything is based on 
changing the orientation of the screen. However, if you tap the screen, the program applies scaling to 
bring the whole image into view with a rectangle showing the section viewed in regular mode: 



^ ' I ::、 


This feature rather complicates the program, but I find it essential. 
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The most crucial part of the XAML file is obviously the Image element. Notice that the Stretch 
property of Image is set to None, and it contains a Bitmoplmoge object with no URI source (as yet). 
The Grid containing that Image is in a Canvas so that it won’t be clipped if it’s larger than the screen 
(and it will be): 


Project: EarthlyDelights I File: MainPage.xaml (excerpt) 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 

<!-- Two items displayed only during downloading --> 

<ProgressBar Name=" progressBar" 

VerticalAli gnment="Center" 

Margin="96 0" /> 

<TextBlock Name="statusText" 

Text="downl oading image …" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Center" /> 

<Canvas> 

<Gri d> 

<Image Stretch="None"> 

<Image.Source> 

<Bitmaplmage x : Name="bi tmaplmage" 

DownloadProgres s="0nBitmapImageDownloadProgress" 
ImageFai1 ed="0nBi tmapImageFai1ed" 
Image0pened="0nBi tmapImageOpened" /> 

</Image.Source> 

</Image> 


<Border Name="outl ineBorder" 
BorderBrush="Whi te" 

HorizontalAli gnment="Left" 
VerticalAli gnment="Top"> 

〈Rectangle Name="outl ineRectangle" 
Stroke="Black" /> 


<Border.RenderTransform> 

<CompositeTransform x : Name="borderTransform" /> 
</Border.RenderTransform> 

</Border> 


<Grid.RenderTransform> 

<CompositeT ransform x : Name="i mageT ransform" /> 
</Grid.RenderTransform> 

</Gri d> 

</Canvas> 


<TextBlock Name="ti tleText" 

Margi n="2 "/ > 

</Grid> 

The Border with the embedded Rectangle is used in the zoomed out view to show the part of the 
image that normally occupies the whole screen, but you can see that rectangle in the normal view 
as well. The outer CompositeTransform applies to both the Image and Border. In the normal view, this 
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transform does nothing. The inner CompositeTronsform orients the Border to the same area of the 
picture that’s viewable in normal mode. 

The Loaded handler checks whether the OrientationSensor is available and, if so, starts a download 
going by simply setting the UriSource property of the Bitmoplmoge object. If the bitmap downloads 
OK, the pixel dimensions can be obtained, and these along with page dimensions are saved as fields: 


Project: EarthlyDelights | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 


OrientationSensor orientationSensor = OrientationSensor .GetDefault(); 
double pageWidth, pageHeight, maxDimension; 
int imageWidth, imageHeight; 

string title = "The Garden of Earthly Delights by Hieronymus Bosch" ; 
double zoomlnScale; 
double rotation; 
bool isZoomView; 


public MainPage() 

{ 

this. Ini tializeComponent(); 

DisplayProperties .AutoRotationPreferences = DisplayProperties .NativeOrientation; 
Loaded += OnMainPageLoaded; 

SizeChanged += OnMainPageSizeChanged; 


async void OnMai nPageLoaded (object sender, RoutedEventArgs args) 

{ 

if (orientationSensor == null) 

{ 

await new MessageDial ogC'OrientationSensor is not available", 

"Earthly Delights") .ShowAsyncQ ; 


progressBar.Visibi1ity = Visibility .Collapsed; 
statusText.Vi sibi1ity = Visibility .Collapsed; 

} 

else 

{ 

bitmaplmage.UriSource = 

new Uri ("http://upload.wikimedia.org/ … Bosch_High_Resolution_2.jpg' 1 ); 

} 


void OnMai nPageSi zeChanged(object sender, SizeChangedEventArgs args) 

{ 

// Save the page dimensions 

pageWidth = this .ActualWidth; 

pageHeight = this .Actual Height; 

maxDimension = Math .Max(pageWidth, pageHeight); 
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// Initialize some values 
outlineBorder.Width = pageWidth; 
outlineBorder.Height = pageHeight; 
borderTransform.CenterX = pageWidth / 2; 
borderTransform.CenterY = pageHeight / 2; 


void OnBitmapImageDownloadProgress (object sender, DownloadProgressEventArgs args) 

{ 

progressBar.Value = args.Progress; 

} 


async void OnBitmapImageFai1ed (object sender, Except!onRoutedEventArgs args) 

{ 

progressBar.Visibility = Visibility .Collapsed; 
statusText.Vi sibi1ity = Visibility .Collapsed; 


await new MessageDialogC'Could not download image: " + args.ErrorMessage, 

"Earthly Delights") .ShowAsyncO ; 


void OnBitmapImageOpened (object sender, RoutedEventArgs args) 

{ 

progressBar.Vi sibi1ity = Visibility .Collapsed; 
statusText.Vi sibi1ity = Visibility. Collapsed; 

// Save image dimensions 

imageWidth = bitmaplmage.PixelWidth; 

imageHeight = bitmaplmage.Pixel Height; 

titleText.Text = String .Format("{0} ({1}\x00D7{2}) " , title, imageWidth, imageHeight); 


// Initialize image transforms 

zoomlnScale = Math .Min(pageWidth / imageWidth, pageHeight / imageHeight); 

// Start OrientationSensor going 
if (orientationSensor != null) 

{ 

ProcessNewOrientationReading(orientationSensor.GetCurrentReadingO); 

orientationSensor.Reportlnterval = orientationSensor.MinimumReportInterval; 

orientationSensor.ReadingChanged += OnOrientationSensorReadingChanged; 

} 

} 

async void OnOrientationSensorReadingChanged (OrientationSensor sender, 

OrientationSensorReadingChangedEventArgs args) 

{ 

await this .Dispatcher.RunAsync(CoreDi spatcherPriority. Normal,()=> 

{ 

ProcessNewOrientationReadingCargs.Readi ng); 

})； 

} 

} 
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The ProcessNewOrientotionReoding method creates a Matrix 3D object from the 
SensorRo toti on Mo trix and uses that to derive a Horizon talCoordino te value: 


Project: EarthlyDelights | File: MainPage.xaml.es (excerpt) 

void ProcessNewOrientationReading (OrientationSensorReading orientationReading) 
{ 

if (orientationReading == null) 
return ; 

// Get the rotation matrix & convert to horizontal coordinates 
SensorRotati onMatri x m = ori entati onReadi ng.Rotati onMatri x; 

if (m == null) 
return ; 


Matrix3D matrix3d = new Matrix3D(m.Mll, 

m.M12, 

m.M13, 

0, 

m.M21, 

m.M22, 

m.M23, 

0, 

m.M31, 

m.M32, 

m.M33, 

0 , 

0 , 0 , 

0 ， 1); 




if (!matrix3d.Haslnverse) 
return ; 


Horizontal Coordinate horzCoord = HorizontalCoordinate .FromMotionMatri x(matri x3d); 


// Set the transform center on the Image element 
imageTransform.CenterX = (imageWidth + maxDimension) * 

(180 + horzCoord.Azimuth) / 360 - maxDimension / 2; 
imageTransform.CenterY = (imageHeight + maxDimension) * 

(90 - horzCoord.Altitude) / 180 - maxDimension / 2; 

// Set the translation on the Border element 

borderTransform.TranslateX = imageTransform.CenterX - pageWidth / 2; 
borderTransform.TranslateY = imageTransform.CenterY - pageHeight / 2; 

// Get rotation from Tilt 
rotation = -horzCoord.Tilt; 

UpdatelmageTransformsO ; 


That method is responsible for setting some of the transforms; the others are set in the 
UpdotelmogeTronsforms method (a call to which you’ll see right at the end of that method). When the 
azimuth is 0 (which occurs when the tablet is pointed north) and the altitude is 0 (when the tablet is 
upright), the CenterX and CenterY properties are set to the center of the bitmap. Otherwise, they are 
set to values along the whole width and height, including a margin so that there’s a wrapping area 
where no part of the image can be seen. (Otherwise, the program would need to show both the right 
edge of the bitmap at the left of the screen and the left edge at the right of the screen.) 
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I wanted the zooming operation to be animated, so I gave Main Page a dependency property that 
is the target of an animation when the screen is tapped: 


Project: EarthlyDelights I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

// Dependency property for zoom-in transition animation 
static readonly DependencyProperty interpolationFactorProperty = 

DependencyProperty .Register ("InterpolationFactor" , 

typeof(doubl e) , 
typeof (MainPage) , 

new PropertyMetadata(0 .0, OnlnterpolationFactorChanged)); 


// Interpolation Factor property 

public static DependencyProperty InterpolationFactorProperty 

{ 

get { return interpolationFactorProperty; } 

} 


public double InterpolationFactor 

{ 

set { SetValue(InterpolationFactorProperty, value); } 

get { return (doubl e)GetValue(InterpolationFactorProperty); } 

} 

protected override void OnTappedCTappedRoutedEventArgs e) 

{ 

// Animate the InterpolationFactor property 
DoubleAnimation doubleAnimation = new DoubleAnimation 
{ 

EnableDependentAnimati on = true , 

To = i sZoomView ? 0 : 1, 

Duration = new Duration(TimeSpan .FromSeconds(l)) 

}； 

Storyboard .SetTarget(doubleAnimation, this) ; 

Storyboard .SetTargetProperty(doubleAnimation ， "InterpolationFactor") ; 

Storyboard storyboard = new StoryboardO ; 

storyboard.Chi 1dren.Add(doubleAnimation); 

storyboard.Begin(); 

isZoomView a= true ; 

base.OnTapped(e); 


static void OnlnterpolationFacto rChangedCDependencyObject obj ， 

DependencyPropertyChangedEventArgs args) 

{ 

(obj as MainPage) .UpdatelmageTransformsC); 

} 
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That OnlnterpolotionFoctorChanged method also calls UpdotelmogeTransforms, which does the 
bulk of the heavy lifting: 


Project: EarthlyDelights I File: MainPage.xaml.es (excerpt) 

void UpdatelmageTransforms() 

{ 

// If being zoomed out, set scaling 

double interpolatedScale = 1 + InterpolationFactor * (zoomlnScale - 1); 
imageTransform.ScaleX = 

imageTransform.ScaleY = interpolatedScale; 

// Move transform center to screen center 

imageTransform.TranslateX = pageWidth / 2 - imageTransform.CenterX; 
imageTransform.TranslateY = pageHeight / 2 - imageTransform.CenterY; 

// If being zoomed out, adjust for scaling 
imageTransform.TranslateX -= InterpolationFactor * 

(pageWidth / 2 - zoomlnScale * imageTransform.CenterX); 
imageTransform.TranslateY -= InterpolationFactor * 

(pageHeight / 2 - zoomlnScale * imageTransform.CenterY); 

// If being zoomed out, center image in screen 
imageTransform.TranslateX += InterpolationFactor * 

(pageWidth - zoomlnScale * imageWidth) / 2; 
imageTransform.TranslateY += InterpolationFactor * 

(pageHeight - zoomlnScale * imageHeight) / 2; 

// Set border thickness 

outlineBorder.BorderThickness = new Thi ckness(2 / interpolatedScale); 
outlineRectangle.StrokeThickness = 2 / interpolatedScale; 

// Set rotation on image and border 

imageTransform.Rotation = (1 - InterpolationFactor) * rotation; 
borderT ransform.Rotati on = -rotation; 


This method is called when there’s a new OrientotionSensor value, or when the InterpolationFoctor 
property changes for the zooming operation. If you're interested in understanding how this method 
works, you might want to clean it up by eliminating all the interpolation code. Set InterpolationFoctor 
to 0 and then to 1, and you’ll see that it’s rather straightforward. 


Bing Maps and Bing Map Tiles 

The Geolocator class is not considered to be a sensor, and it’s in another namespace entirely: 

Windows.Devices.Geolocotion. Yet it's similar in that you start it going and it tells you when the 
computer has changed geographic location and what that location is. 

You need to specifically indicate in the Capabilities section of the Package.appxmanifest file that 
your application requires Location information. Windows 8 then gets a confirmation from the user the 
first time the program runs. 
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Generally, you’ll use the Geolocator location in connection with maps. A Bing Maps control is not 
built into Windows 8, but you can download a toolkit that lets you add it to your application. You’ll 
need a credentials key that you can get from visiting www.bingmapsportal.com. 

But I’m going to take a somewhat different approach for the last program in this chapter. I’m going 
to show you a map that rotates based on the orientation of the tablet. This rotation allows north on 
the map to be aligned with actual north (or whatever the tablet believes north to be). To do this, I 
don’t use the Bing Maps control; instead, I’ll use the Bing Maps SOAP service to download individual 
tiles and stitch them together into a composite map. A credentials key is still required. 

When you run the RotatingMap program, you're going to want to use your fingers to scan and 
scale the map. It won’t work. The program has no touch interface! To keep things simple, the program 
simply centers the map at the current location and reorients the map if the location changes. The 
program does provide application bar buttons for zooming in and zooming out, and for switching 
between road and aerial views, but that’s it. 

Here’s the XAML file. All the tiles constituting the map go into the Canvas named imogeConvas. 
Notice the RotateTransform to rotate the Canvas around its center. 


Project: RotatingMap I File: MainPage.xaml (excerpt) 


<Page … > 

<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
<Canvas Name="imageCanvas" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Center"> 

<Canvas.RenderTransform> 

<RotateTransform x : Name="i mageCanvasRotate" /> 

</Canvas.RenderTransform> 

</Canvas> 


<!-- Circle to show location --> 

<E11ipse Name="locati onDisplay" 

Width= M 24" 

Height="24" 

Stroke="Red" 

StrokeThi ckness="6" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Center" 
Visibility="Collapsed" /> 

<!-- Arrow to show north --> 

<Border HorizontalAli gnment="Left" 

VerticalAli gnment="Top" 

Margin="12" 

Background:" Black” 

Width="36" 

Height="36" 

CornerRadi us="18"> 

<Path Stroke="Whi te" 

StrokeThi ckness="3" 

Data="M 18 4 L 18 24 M 12 12 L 18 4 24 12"> 
<Path.RenderTransform> 

<RotateTransform x : Name="northArrowRotate" 
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CenterX="18" 


CenterY="18" /> 
</Path.RenderTransform> 

</Path> 

</Border> 


<!-- "powered by bing" display --> 

<Border Background="Bl ack" 

HorizontalAli gnment="Center" 

VerticalAli gnment="Bottom" 

Margin="12" 

CornerRadi us="12" 

Padding="3"> 

<StackPanel Name="poweredByDi splay" 
Orientation="Horizontal " 

Vi sibi1i ty="Col 1apsed"> 

<TextB"lock Text=" powered by " 

Foreground="Whi te" 

VerticalAli gnment="Center" /> 

<Image Stretch="None"> 

<Image.Source> 

<Bitmaplmage x : Name="poweredByBi tmap" /> 
</Image.Source> 

</Image> 

</StackPanel> 

</Border> 

</Grid> 


<Page.BottomAppBar> 

<AppBar Name="bottomAppBar" 

IsEnabled="Fal se"> 

<StackPanel Orientati on="Hori zontal" 

HorizontalAlignment="Ri ght"> 


<!-- Must remove reference to BackgroundCheckedGlyph in 
AppBarButtonStyle to use it for a CheckBox --> 

<CheckBox Name="streetVi ewAppBarButton" 

Styl e="{StaticResource StreetAppBarButtonStyl e} 
AutomationProperties. Name="Street View" 
Checked="OnStreetVi ewAppBarButtonChecked" 
Unchecked="OnStreetVi ewAppBarButtonChecked" /> 

<Button Name="zoomInAppBarButton" 

Styl e="{StaticResource ZoomlnAppBarButtonStyl e}" 
Cli ck="OnZoomInAppBarButtonClick" /> 

〈Button Name="zoomOutAppBar Button" 

Styl e="{StaticResource ZoomOutAppBarButtonStyl e}" 
Cli ck="OnZoomOutAppBarButtonClick" /> 
</StackPanel> 

</AppBar> 

</Page.BottomAppBar> 

</Page> 
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It’s possible to use the Bing Maps SOAP service "manually” by transferring hairy XML files back and 
forth, but a much saner approach is using the Web service through a proxy class that Visual Studio 
generates. This proxy class makes the Web service appear to be a bunch of structures, enumerations, 
and asynchronous method calls. To add this proxy to the RotatingMap program, I right-clicked the 
project name in the Solution Explorer in Visual Studio and selected Add Service Reference from the 
menu. When the dialog box requested an address, I pasted in the URL for the Imagery Service (which 
you can find at http://msdn.microsoft.com/en - us/librory/cc966738.aspx with URLs for three other Web 
services connected with Bing Maps). I gave it a name of ImageryService, which means that Visual 
Studio generates code using the namespace RotatingMap. Imagery Service. 

This service has two types of requests: GetMapUriAsync and G e tlm ag eryMe to da to A syn c. The first 
allows obtaining a static map of a particular location, but I gravitated toward the other, which allows 
you to obtain information necessary for downloading individual map tiles that you can then assemble 
into a complete map. 

Let’s begin looking at RotatingMap code with the Main Page constructor. You see that it saves only 
two values as application settings: the map style (a member of the MapStyle enumeration, which is 
among the code generated for the web service, indicating road or aerial view) and an integer zoom 
level: 


Project: RotatingMap I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

// Saved as application settings 
MapStyle mapStyle = MapStyle .Aerial; 
int zoomLevel = 12; 

public MainPageC) 

{ 

this. InitializeComponent(); 

DisplayProperties .AutoRotationPreferences = DisplayProperties. NativeOrientation; 
Loaded += OnMainPageLoaded; 

SizeChanged += OnMainPageSizeChanged; 

// Get application settings (and later save them) 

IPropertySet propertySet = ApplicationData. Current.LocalSettings.Values; 

if (propertySet.Contai nsKeyC'ZoomLevel")) 

zoomLevel = (i nt)propertySet ["ZoomLevel"] ; 

if (propertySet.Contai nsKeyC'MapStyle")) 

mapStyle = (MapStyl e) (i nt) propertySet ["MapStyle"] ; 

Application .Current.Suspending += (sender, args)=> 

{ 

propertySet ["ZoomLevel "] = zoomLevel; 
propertySet ["MapStyle"] = (int)mapStyle; 

}； 
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The Web service is accessed solely in the Loaded handler. Two calls must be made: one to get maps 
metadata for the road view, and the other for the aerial view. The information is saved in two instanc¬ 
es of a local class named ViewParams. The most important part of this metadata is a URI template for 
downloading individual map tiles. The ViewParams class also has fields for the minimum and maxi¬ 
mum zoom levels, but I know the zoom level ranges from 1 to 21 and you’ll see that other parts of 
the code assume an upper limit of 21: 


Project: RotatingMap | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 


// Storage of parameters for two views 
class ViewParams 


public string UriTemplate; 
public int MinimumLevel; 
public int MaximumLevel; 


ViewParams aerialParams; 
ViewParams roadParams; 


Geolocator geolocator = new GeolocatorO ; 

Inclinometer inclinometer = Inclinometer.GetDefaultC); 


async void OnMainPageLoaded (object sender, RoutedEventArgs args) 

{ 

// Initialize the Bing Maps imagery service 
ImageryServiceClient imageryServiceClient = 
new ImageryServiceClient( 

ImageryServiceClient.EndpointConfigurati on. BasicHttpBinding_IImageryService); 

// Make two requests for road and aerial views 
ImageryMetadataRequest request = new ImageryMetadataRequest 
{ 

Credentials = new Credentials 

{ 

Applicationld = "put your own credentials string here" 

}, 

Style = MapStyle. Road 

}； 

Task<ImageryMetadataResponse> roadStyleTask = 

imageryServiceClient.GetlmageryMetadataAsyncCrequest); 


request = new ImageryMetadataRequest 

{ 

Credentials = new Credentials 

{ 

Applicationld = "put your own credentials string here" 

}, 

Style = MapStyle. Aerial 

}； 

Task<ImageryMetadataResponse> aerialStyleTask = 

imageryServiceClient.GetlmageryMetadataAsyncCrequest); 
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// Wait for both tasks to complete 

Task. WaitAl1(roadStyleTask, aerialStyleTask); 


// Check if everything is OK 

if (!roadStyleTask.IsCanceled && !roadStyleTask.IsFaulted && 

!aerialStyleTask.IsCanceled && !aerialStyleTask.IsCanceled) 

{ 

// Get the "powered by" bitmap 

poweredByBitmap.UriSource = roadStyleTask.Result.BrandLogoUri; 
poweredByDisplay.Visibility = Visibility .Visible; 


// Get the URIs and min/max zoom "levels 

roadParams = CreateViewParams(roadStyleTask.Result.Results[0]); 
aerialParams = CreateViewParams(aerialStyleTask.Result.Results[0]); 

// Get the current location 

Geoposition geoPosition = await geolocator.GetGeopositionAsync(); 
GetLongitudeAndLatitude(geoPosition.Coordinate); 

RefreshDisplay(); 


// Get updated locations 

geolocator.PositionChanged += OnGeolocatorPositionChanged; 

// Enable the application bar 
bottomAppBar.IsEnabled = true; 

streetViewAppBarButton.IsChecked = mapStyle == MapStyle .Road; 


// Get the current yaw 
if (inclinometer != null) 

{ 

SetRotation(inclinometer.GetCurrentReading()); 
inclinometer.ReadingChanged += OnlnclinometerReadingChanged; 

} 



ViewParams CreateViewParams (ImageryMetadataResult result) 

{ 

string uri = result.ImageUri; 

uri = uri.Repl ace("{subdomain}" , result.ImageUriSubdomains[0]); 
uri = uri.Repl ace("&token={token}" , "") ; 
uri = uri.Repl ace("{culture}" , "en-us") ; 

return new ViewParams 

{ 

UriTemplate = uri ， 

MinimumLevel = result.ZoomRange.From, 

MaximumLevel = result.ZoomRange.To 

}； 


Two asynchronous calls are required to obtain the metadata for the two views, yet the two calls 
aren’t dependent on each other, so they can proceed at the same time. This seemed like a perfect 
application of the Tosk.WaitAII method, which waits until multiple Task items have completed. 
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When both Web service calls have completed successfully, the Geolocotor and Inclinometer are 
started up. The Inclinometer is used solely to obtain a yaw value used for rotating the map and for 
rotating an arrow indicating north: 

Project: RotatingMap | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 
{ 

async void OnlnclinometerReadingChanged(Inc1 inometer sender, 

InclinometerReadingChangedEventArgs args) 

{ 

await this. Dispatcher.RunAsync(CoreDi spatcherPriority .Normal,()=> 

{ 

SetRotation(args.Reach ng); 

}); 

} 

void SetRotation(Incl inometerReading inclinometerReading) 

{ 

if (inclinometerReading == null) 
return ; 

imageCanvasRotate.Angle = inclinometerReading.YawDegrees; 
northArrowRotate.Angle = inclinometerReading.YawDegrees; 

} 

} 

Following completion of the Loaded handler, the program has two URI templates that it can use to 
download individual map tiles. The tiles that form the basis of Bing Maps are bitmaps that are always 
256 pixels square. Each tile is associated with a particular longitude, latitude, and zoom level and 
contains an image of part of the world flattened using the common Mercator projection. 

In Level 1, the entire Earth — or, rather, that part of the Earth with latitudes between positive and 
negative 85.05 degrees — is covered by four tiles: 


Q AO..CMM. 1 
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I’ll discuss the numbers in these tiles shortly. The tiles are 256 pixels square, so at the equator each 
pixel covers about 49 miles. 


In Level 2,16 tiles cover the Earth: 


00 一 

01 

10 

11 

02 •一 

03 

12 f 

13 

20 

21 


31 

22 

23 

32 

33 


These tiles are also 256 pixels square, so at the equator each pixel is about 24 miles. 

Each tile in Level 1 covers the same area as four tiles in Level 2, and the trend continues in this way: 
Level 3 has 64 tiles, Level 4 has 256 tiles, and up and up to Level 21, which (in principle, anyway) cov¬ 
ers the Earth with more than 4 trillion tiles — 2 million horizontally and 2 million vertically for a resolu¬ 
tion at the equator of 3 inches per pixel. 

How can so many tiles possibly be organized in a coherent manner? Keep in mind that three 
dimensions are involved — longitude, latitude, and zoom level — and for maximum efficiency in 
providing these tiles through a Web service, tiles covering the same area should be stored near each 
other on the servers. 

Obviously, a very clever numbering scheme is called for, and it’s called a quodkey. Each tile has 
a unique quad key. The URI templates just obtained from the Bing Maps Web service contain a 
placeholder "{quadkey }〃 that you replace to reference an actual tile. The two diagrams indicate the 
quadkeys for these particular tiles in the upper left corner. Leading zeroes are important! The number 
of digits in the quadkey is equal to the zoom level. The tiles in Level 21 are identified with 21-digit 
quadkeys. 

The digits in a quadkey are always 0,1, 2, or 3, which indicates that quadkeys are actually base-4 
numbers. In binary, the digits 0,1, 2, and 3 are 00, 01,10, and 11. The first bit is a vertical coordinate, 
and the second bit is a horizontal coordinate. Thus, the bits correspond to an interleaved longitude 
and latitude. 

As you’ve seen, each tile in Level 1 corresponds to four tiles in Level 2, so you can think of tiles as 
having parent and child relationships. The quadkey of a child tile always begins with the same digits 
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as its parent but adds another digit, depending on its location relative to its parent. You can obtain a 
parent quadkey from a child quadkey by simply lopping off the last digit. 


To use the Bing Maps Web service, it’s necessary to derive a quadkey from a longitude and 
latitude. The code in the following GetLongitude And Latitude method shows the first step, which is to 
convert the longitude and latitude from the Geolocator into relative double values ranging from 0 to 
1, and then into integer values: 

Project: RotatingMap | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 
{ 

const int BITRES = 29; 

int integerLongitude = -1; 
int integerLatitude = -1; 

async void OnGeolocatorPositionChanged(Geol ocator sender, PositionChangedEventArgs args) 

{ 

await this .Dispatcher.RunAsync(CoreDi spatcherPriority .Normal,()=> 

{ 

GetLongitudeAndLatitude(args■Position.Coordi nate); 

RefreshDisplayC); 

})； 

} 


void GetLongitudeAndLatitude (Geocoordinate geoCoordinate) 

{ 

locatiOnDisplay.Visibility = Visibility .Visible; 

// Calculate integer longitude and latitude 

double relativeLongitude = (180 + geoCoordinate.Longitude) / 360; 
integerLongitude = (i nt) (relativeLongitude * (1 « BITRES)); 

double sinTerm = Math .Sin (Math .PI * geoCoordinate.Latitude / 180); 

double relativeLatitude =0.5- Math. Log((1 + sinTerm) / (1 - sinTerm)) / (4 * Math. PI); 
integerLatitude = (int) (relativeLatitude * (1 « BITRES)); 


The BITRES value is 29 to account for the 21 bits in a Level 21 quadkey plus 8 bits for the pixel 
size of the tile, which means that these integer values identify a longitude and latitude precise to 
the nearest pixel of a tile at the highest zoom level. The calculation of integerLongitude is trivial, but 
integer Latitude is more complex because the Mercator map projection compresses latitudes as you 
get farther from the equator. 


An example: The center of Central Park in New York City has a longitude of-73.965368 and 
a latitude of 40.783271. The relative double values (to just a few decimal places) are 0.29454 and 
0.37572. The 29-bit integer values (shown in binary and grouped in fours for easy readability) are: 

0 1001 0110 1100 1110 0000 1000 oooo 
0 1100 0000 0101 1110 1011 0000 0000 
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Suppose you want a tile for this longitude and latitude in a Level 12 zoom. You need the top 12 
bits of these integer longitudes and latitudes. (Watch out! The resultant digits are grouped a little 
differently.) 

0100 1011 0110 
0110 oooo 0010 

These are two binary numbers, but to form a quadkey they need to be combined into a base-4 
number. You can't do this in code without actually looping through the bits, but for illustrative pur¬ 
poses, you can simply double all the bits in the latitude and add the two values as if they were base-4 
values: 

0100 1011 0110 
+ 0220 0000 0020 

0320 1011 0130 

And that’s the quadkey you’ll need to substitute for the 〃 {quadkey }〃 placeholder in the URI 
templates obtained from the Web service. The resultant URI references a 256-pixel-square bitmap. 

Here’s the routine in RotatingMap that constructs a quadkey from the truncated integer longitudes 
and latitudes. For clarity, the logic has been separated to show first the derivation of a long integer 
and then a string: 

Project: RotatingMap I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 
{ 

■ ■ ■ 

StringBui1der strBui1der = new StringBui lder() ; 

■ ■ ■ 

string ToQuadKeyCi nt longitude, int latitude, int level) 

{ 

long quadkey = 0; 
int mask = 1 « (level - 1); 

for (i nt i = 0; i < "level; i++) 

{ 

quadkey «= 2; 

if ((longitude & mask) != 0) 
quadkey |= 1; 

if ((latitude & mask) != 0) 
quadkey |= 2; 

mask >>= 1; 

} 

strBui "I der .Cl earO ; 
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for (int i =0; i < level; i++) 

{ 

strBuilder.Insert(0, (quadkey & 3).ToString()); 
quadkey »= 2; 

} 

return strBuiIder.ToStringO ; 

} 


The quadkey references a tile containing the desired longitude and latitude, but the location of 
the precise longitude and latitude is actually somewhere within the tile. The pixel location within the 
tile can be determined by the next 8 digits of the integer longitude and latitude following the digits 
required for the quadkey. 

We Ye in the home stretch now. Because the whole page must be covered with 256-pixel-square 
tiles, because this array of tiles is rotatable, and because the current location of the user is positioned 
in the center of the screen somewhere within the central tile, the SizeChanged handler determines 
how many tiles are required and hence how many Image elements need to be created. The field 
named sqrtNumTiles means "the square root of the number of tiles.’’ For a 1366 by 768 pixel display, 
it’s calculated as 9. The total number of tiles (and Image elements) is the square of that, or 81. 

Project: RotatingMap | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 
{ 

int sqrtNumTiles; // always an odd number 

void OnMainPageSi zeChanged(object sender, SizeChangedEventArgs args) 

{ 

// Cl ear out the existing Image elements 
imageCanvas.Children.Clear(); 

// Determine how many Image elements are needed 

double diagonal = Math . Sqrt(Math .Pow(args.NewSize.Width, 2) + 

Math. Pow(args.NewSize.Height, 2)); 

sqrtNumTiles = 1 + 2 * (int)Math. Ceiling((diagonal / 2) / 256); 

// Create Image elements for a sqrtNumTiles x sqrtNumTiles array 
for (int i =0; i < sqrtNumTiles * sqrtNumTi1es; i++) 

{ 

Image image = new Image 
{ 

Source = new Bitmaplmage() , 

Stretch = Stretch .None 

}； 

imageCanvas.Children.Add(image); 

} 

RefreshDisplay(); 

} 


} 
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The RefreshDisploy method does the real work. It loops through all the Image elements and 
determines the quad key (and hence a URI) for each one: 


Project: RotatingMap I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 


void RefreshDisplayO 

{ 

if (roadParams == null | | aerialParams == null) 
return ; 

if (integerLongitude == -1 || integerLatitude == -1) 
return ; 


// Get coordinates and pixel offsets based on current zoom level 
int croppedLongitude = integerLongitude » BITRES - zoomLevel; 
int croppedLatitude = integerLatitude » BITRES - zoomLevel; 
int xPixelOffset = (integerLongitude » BITRES - zoomLevel - 8) % 256; 
int yPixelOffset = (integerLatitude » BITRES - zoomLevel - 8) % 256; 


// Prepare for the loop 

string uriTemplate = (mapStyle == MapStyle.Road ? roadParams : aerialParams). 

UriTemplate; 
int index = 0; 

int maxValue = (1 « zoomLevel) - 1; 


// Loop through the array of Image elements 

for (i nt row = -sqrtNumTiles / 2; row <= sqrtNumTiles / 2; row++) 

for (i nt col = -sqrtNumTi1es / 2; col <= sqrtNumTi1es / 2; col++) 

{ 

// Get the Image and Bitmaplmage 

Image image = imageCanvas.Children[index] as Image ; 

Bitmaplmage bitmap = image.Source as Bitmaplmage; 
index++; 


// Check if we've gone beyond the bounds 
if (croppedLongitude + col < 0 || 

croppedLongitude + col > maxValue || 
croppedLatitude + row < 0 || 
croppedLatitude + row > maxValue) 

{ 

bitmap.UriSource = null; 

} 

else 

{ 

// Calculate a quadkey and set URI to bitmap 
int longitude = croppedLongitude + col; 
int latitude = croppedLatitude + row; 

string strQuadkey = ToQuadKey(longitude, latitude, zoomLevel); 
string uri = uriTempi ate.Replace ("{quadkey}" , strQuadkey); 
bitmap.UriSource = new Uri (uri); 
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// Position the Image element 

Canvas .SetLeft(image, col * 256 - xPixelOffset); 
Canvas .SetTop(image, row * 256 - yPixelOffset); 


The only part left involves the application bar buttons. The increase and decrease zoom buttons 
are carefully enabled and disabled based on the minimum and maximum zoom levels for the cur¬ 
rently selected view although (as I’ve said) other parts of the program are apparently quite certain 
that the maximum zoom level is 21: 


Project: RotatingMap | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 


void OnStreetViewAppBarButtonChecked (object sender, RoutedEventArgs args) 

{ 

ToggleButton btn = sender as ToggleButton ; 

ViewParams viewParams = null; 


(btn■IsChecked.Value) 


{ 


mapStyle = MapStyle. Road; 
viewParams = roadParams; 


} 

else 

{ 


mapStyle = MapStyle .Aerial 
viewParams = aerialParams; 


} 


zoomLevel = Math .Max(viewParams.MinimumLevel, 

Math .Min(viewParams.MaximumLevel, zoomLevel)) 


RefreshDisplayO ; 
RefreshButtonsO ; 


void OnZoomlnAppBarButtonCli ck(object sender, RoutedEventArgs args) 

{ 

zoomLevel += 1; 

Ref reshDi splayO ; 

RefreshButtonsO ; 

} 


void OnZoomOutAppBarButtonCli ck(object sender, RoutedEventArgs args) 

{ 

zoomLevel -= 1; 

Ref reshDi splayO ; 

RefreshButtonsO ; 


void RefreshButtonsO 
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ViewParams viewParams = 

streetViewAppBarButton.IsChecked.Value ? roadParams : aerialParams; 
zoomlnAppBarButton.IsEnabled = zoomLevel < viewParams.MaximumLevel; 
zoomOutAppBarButton.IsEnabled = zoomLevel > viewParams.MinimumLevel; 



We’re not quite accustomed to seeing familiar regions of a map rotated, so the island of 
Manhattan looks a little odd in this view: 



But if you’re standing in a strange neighborhood with your tablet trying to figure out where you 
are, having the map rotate in accordance with reality can be very helpful. Maybe someday the labels 
showing cities and streets can be rotated as well. 
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CHAPTER 19 

Pen (Also Known as Stylus) 


A n aura of controversy surrounds this chapter. The subject is an input device that has an uncertain 
future in computing, and passions are strong on each side of the issue: In 2010, Steve Jobs 
discussed the possibility of other tablets attempting to compete with the iPad and declared, "If you 
see a stylus, they blew it." 1 

Yet, anyone who’s tried to use a traditional mouse-based application on a touch screen would 
certainly disagree. The stylus is not quite as convenient as a finger or as versatile as multiple fingers, 
but it’s nearly as precise as a mouse and usually works much better than fingers for picking items 
from menus and selecting and erasing input. The Samsung 700T that I’ve been using for most of this 
book has a stylus, and I consider it essential for using Visual Studio on the machine when a mouse 
isn’t attached. 

I was therefore in great suspense awaiting the introduction of the first Microsoft Surface devices. 
Would a stylus be included? I was even contemplating that the answer to that question would govern 
whether a chapter on the stylus would be included in this book! 

By Steve Jobs's criterion, the Microsoft Surface certainly did not "blow it.” The first Surface 
computers do not include a stylus. I was disappointed, but I elected to include this chapter in the 
book regardless. 

I personally prefer the word stylus for referring to these input devices, but from here on the 
terminology in this chapter will be consistent with the Windows Runtime programming interface, 
where it’s called a pen. Often the pen input and rendered graphical output is referred to as ink. 

By virtue of having read Chapter 13, "Touch, Etc.〆’ you already know how to process and render 
pen input. However, the Windows. Ul. Input Inking namespace provides additional facilities when 
working with pens. These features include 

■ Erasure and selection modes in addition to inking 

■ Converting polyline input to Bezier curves for smoother rendition 

■ Handwriting recognition 


1 David Pogue, "On Touch Screens, Rest Your Finger by Using a Stylus," New York Times, August 1, 2012. 

http://www.nytimes.eom/2012/08/02/technology/personoltech/on-touch-screens-rest-your-finger-by-using-a-stylus- 

state-of-the-art.html 
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■ Saving ink to files and loading ink from files 
I won't be exploring handwriting recognition in this chapter, however. 

Interestingly, none of these facilities actually requires a pen! Theoretically, you can do everything 
in this chapter with touch or mouse input. However, touch or mouse input is awkward for handwrit¬ 
ing because text drawn with fingers is often too large, while text drawn with the mouse is often too 
jittery. The pen is just right. That’s to be expected from a device of a size and shape used for writing 
for at least two millennia. 

The article from the New York Times that I cited earlier was all about capacitance pens. These are 
pens designed to supplement fingers on capacitance touch screens. They offer no real advantages 
over fingers except in precision and maneuverability. 

Of much more versatility is an electromagnetic pen, sometimes referred to as a digitizer or digital 
stylus, but these pens require a screen that can respond to this type of pen input. Such is the case 
with the Samsung 700T tablet I’m using for this book. The pen has a small tip (about 1 mm in diam¬ 
eter), an "eraser" at the opposite end, and a button on the barrel. The PointerPointProperties class 
defines two properties, IsEroser and Islnverted, that are both true if the eraser is touching the screen 
rather than the pen tip. This is generally used for erasing earlier input. The IsBorrelButtonPressed 
property is true if the tip is being used and the barrel button is pressed. This is generally used for 
selection. 

Unless you're writing a program specifically for electromagnetic pen users, you’ll want to 
supplement the erase and selection facilities of the pen with software options, but to streamline the 
sample projects I’ll skip that amenity in this chapter. 


The InkManager Collections 

The Windows. Ul. Input Inking namespace revolves around the InkManager class. This class is your 
application’s portal into many of the features associated with pen use. 

An InkManager instance maintains all the ink for a particular page of input. If your program 
implements a pad of sorts — as the last program in this chapter does — then each page of that pad will 
have its own InkManager. 

An InkManager object maintains a collection of objects of type InkStroke. Each InkStroke is a 
continuous curve generally created by touching the pen to the screen, moving it, and lifting it. An 
InkStroke is associated with a particular InkDrowingAttributes object, the primary purpose of which is 
to indicate the color of the stroke and the shape and size of the pen tip, although (as you'll see) the 
InkManager and InkStroke don't really do anything with these drawing attributes. 

Each InkStroke contains a collection of InkStrokeRenderingSegment objects. An 
InkStrokeRenderingSegment is a single Bezier curve with a particular pen pressure, tilt, and twist. The 
pressure is often used for computing a line thickness when rendering strokes. The value can range 
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from 0 to 1 just like the Pressure property of PointerPointProperties. Pens that support tilt and twist 
are rather rare. 

With help from your program, the InkManager can accumulate pen input and smooth it into Bezier 
curves, but it does no rendering on its own. Rendering is entirely your responsibility, and it's generally 
a two-step operation: 

■ Render lines using Polyline, Line, or Path as the user is drawing or writing with the pen. 

■ Replace these elements with Bezier curves as each stroke is completed. 

You’ve already seen the first rendering step in connection with the FingerPaint programs. To clarify 
the basics of using InkMonoger, let me focus on the second rendering step in the first sample project, 
Simplelnking. The Simplelnking program is so simple that you don’t see what you’re actually drawing 
until you lift the pen from the screen! 


Here’s the XAML file. Notice that I’ve colored the Grid white, which is generally the convention for 
pen input: 


Project: Simplelnking | File: MainPage.xaml (excerpt) 

<Page … > 

<Grid Name="contentGri d" 

Background="Whi te" /> 

</Page> 

By default, pen input is black. 

I’ve used a single InkManager object for the duration of the program: 


Project: Simplelnking I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 
{ 

InkManager inkManager = new InkManagerO ; 
bool hasPen; 

public MainPageO 
{ 

this .Ini ti alizeComponent(); 

// Check if there’s a pen among the pointer input devices 
foreach (Poi nterDevice device in PointerDevi ce.GetPointerDevices()) 
hasPen |= device.PointerDeviceType == PointerDeviceType. Pen; 



The constructor determines whether the machine supports a pen, and if it does, the hasPen field 
is set to true. For this program, I’ve decided to ignore all nonpen pointer input for computers that 
support a pen, but I’ll accept all pointer input for computers that don’t support a pen. This allows the 
program to be used on the Microsoft Surface. 
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The InkManoger defines three methods that you use in conjunction with the Pointer events. These 
methods allow the InkManoger object to accumulate pointer input. They are 

■ ProcessPointerDown, which you'll call from the PointerPressed event handler 

■ ProcessPoin ter Up do te, called multiple times from the Pointer Moved event handler 

■ ProcessPointerUp, called from the PointerReleased event handler 

The argument to each method is a PointerPoint object that you can obtain from 
PointerRoutedEventArgs by calling GetCurrentPoint or GetlntermediatePoints. As you'll recall, the 
PointerPoint object includes not only the position of the pointer but the pointer ID (which allows the 
InkManoger to track multiple pointers) and PointerPointProperties, including pressure and tilt. 

Here's the On Poin ter Pressed override in Simplelnking: 

Project: Simplelnking I File: MainPage.xaml.es (excerpt) 

protected override void OnPointerPressed(Poi nterRoutedEventArgs args) 

{ 

if (args.Pointer.PointerDeviceType == PointerDeviceType .Pen || !hasPen) 

{ 

PointerPoint pointerPoint = args.GetCurrentPoi nt(this) ; 
inkManager.ProcessPointerDownCpointerPoint); 

} 

base .OnPointerPressed(args); 

} 

The //statement checks for a device type of Pen but allows other pointer devices if the computer 
doesn’t support a pen. You can remove the entire /, statement if you want to support all pointer input 
devices regardless. In any case, simply pass the PointerPoint object to the Pro cess Poin ter Down method 
of the InkManoger. Processing OnPointerMoved is just a little more complex: 

Project: Simplelnking | File: MainPage.xaml.es (excerpt) 

protected override void OnPointerMoved(Poi nterRoutedEventArgs args) 

{ 

if ((args.Poi nter. PointerDeviceType == PointerDeviceType. Pen || !hasPen) && 
args■Pointer.IsInContact) 

{ 

IEnumerable<PointerPoint> points = args.GetIntermediatePoi nts(this) .ReverseO; 

foreach (Poi nterPoint point in points) 

inkManager.ProcessPointerUpdateCpoint); 

} 

base .OnPointerMoved(args); 

} 

Calls to ProcessPointerilpdote allow the InkManoger to accumulate pieces of the total ink stroke. For 
maximum fidelity to pen input, the code uses GetlntermediatePoints rather than GetCurrentPoint, 
reversed with the LINQ Reverse operator. 

Notice that the //statement for OnPointerMoved now also includes a check for the IsInContact 
property. As you’ll recall, the pen begins generating OnPointerMoved events when the pen comes 
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within the vicinity of the screen before actually touching the screen. If the //statement did not 
check IslnContact, it would call the ProcessPointerUpdote method of InkMonoger before first calling 
ProcessPointerDown, and that would raise an exception. 

So far, the program hasn’t been doing any drawing. Any reasonable program would have been 
drawing all along. This program reserves all the drawing for the OnPointerReleosed method, but let’s 
look at the InkManoger overhead first: 

Project: Simplelnking | File: MainPage.xaml.es (excerpt) 

protected override void OnPointerReleased(Poi nterRoutedEventArgs args) 

{ 

if (args.Pointer.PointerDeviceType != PointerDeviceType .Pen && hasPen) 
return ; 

inkManager.ProcessPointerUp(args.GetCurrentPoi nt(this)) ; 

// Render the most recent InkStroke 

base .OnPointerReleased(args); 

} 

Before rendering the new InkStroke object, you’ll need to know about InkDro wing A ttributes. 

The Ink Drawing Attributes 

Although InkMonager doesn't perform any rendering on its own, it maintains information about 
attributes involved with rendering ink. This information is encapsulated in the InkDrawingAttributes 
class, which has the following properties and default values: 


Property 

Value 

Color 

Black (OxFFOOOOOO) 

PenTip 

Circle 

Size 

(2,2) 

FitToCurve 

true 

IgnorePressure 

false 


These are the default values when you create a new instance of InkDrowingAttributes on your own, 
and these are the default values for the InkDrowingAttributes that InkMonoger creates and retains 
internally. 

These properties are strictly for the benefit of application programs that need to render ink 
strokes! They do not affect the operation of InkMonager because the InkMonager does no rendering 
on its own. 


CHAPTER 19 Pen (Also Known as Stylus) 1017 










The only other option for PenTip is Rectangle, in which case the Size property (of type Size) 
describes the dimensions of the pen tip. For the default Circle tip, you can use the Width property of 
the Size value for determining the thickness of rendered lines. 

The FitToCurve property indicates if ink should be rendered as Bezier curves; regardless of the 
setting, InkMonoger converts the pointer input to Bezier curves. The IgnorePressure property indi¬ 
cates that ink should be rendered without regard to pressure information, but the InkMonoger still 
includes this pressure information regardless of the setting. 

The InkMonoger creates an InkDrowingAttributes object with these default properties and 
maintains it internally. However, your program can’t get access to that object. If you want to set dif¬ 
ferent default properties for the InkMonoger object, you must do so like this: 

InkDrawingAttributes inkDrawingAttributes = new InkDrawingAttributes() ; 

inkDrawingAttributes.Color = Colors. Red; 

inkDrawingAttributes.Size = new Size(6, 6); 

inkManager.SetDefaultDrawingAttributes(inkDrawingAttributes); 

When you create a new InkDra wing A ttri butes object and pass it to InkMonoger, don’t assume that 
your program and InkMonoger now share this object and any changes to it by your application will 
be reflected in the internal object that InkMonoger maintains. If you make further changes to this 
In kD ro wing A ttri butes, you must then call the SetDefaultDrawing Attributes method again for these 
changes to take effect. 

As you’ve seen, a program using the InkMonoger processes a normal sequence of PointerPressed, 
multiple PointerMoved, and PointerReleasecJ events by calling the InkMonoger methods 
ProcessPointerDown, Process Po in ter Updo te (multiple times), and ProcessPointerilp. When this se¬ 
quence of calls has completed, the InkMonoger creates a new InkStroke and adds it to its collection. 

This InkStroke object represents a continuous stroke of ink from the time the pointer 
touched the screen to the time it was lifted. InkStroke has a Dro win gA ttrib utes property of type 
In kD ro wing A ttri butes that InkMonoger created based on its internal default I nkDrawing Attributes 
object. 

For example, suppose you create a new InkMonoger and handle pointer input by calling 
ProcessPointerDown, Process Po in ter Upda te multiple times, and ProcessPointerilp. The resultant 
InkStroke object has an InkDrawingAttributes object indicating a black pen with a size of (2, 2). 

Now your program creates a new InkDra wing A ttri butes object, sets a couple properties, and 
calls SetDefoultDrowingAttributes using the code I showed earlier. The next sequence of calls to 
ProcessPointerDown, Process Po in ter Upda te, and ProcessPointerilp results in a second InkStroke object, 
but this one has a Dm wing Attributes property indicating a red pen with a size of (6, 6). 

But none of this is set in stone. You can create new InkDrowingAttributes objects and set 
those to the individual InkStroke objects, and you can alter any of the properties of the existing 
In kD ro wing A ttri butes object referenced from the DrowingAttributes property of an InkStroke object. 

Following the call to the ProcessPointerilp method, the InkMonoger converts all the points 
accumulated internally for this new stroke into one or more Bezier curves that make up a new 
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InkStroke object. This new InkStroke is added to its internal collection, which is available from the 
GetStrokes method. 

Because the Simplelnking program renders each stroke when the stroke is completed, it’s only 
interested in the most recent InkStroke in this collection, which it can obtain like so: 

IReadOn"lyList<InkStroke> i nkStrokes = inkManager .GetStrokes(); 

InkStroke inkStroke = inkStrokes[inkStrokes.Count - 1]; 

This InkStroke has a DrawingAttributes property and a collection of InkStrokeRenderingSegmerit 
objects that represent a series of connected Bezier splines. A program can obtain this collection of 
segments by calling GetRenderingSegments. 

Each InkStrokeRenderingSeg merit contains three properties of type Point: 

■ BezierControlPointl 

■ BezierControlPoint2 

■ Position 

In the first InkStrokeRenderingSeg merit object in the collection, these three points are the same. 
This is the first point of the complete curve. Each subsequent InkStrokeRenderingSegment continues 
from that point with two control points and an end point. 

In addition, each InkStrokeRenderingSegment also contains four properties of type float: 

■ Pressure 

■ TiltX 


■ TiltY 

■ Twist 

These are obviously for much fancier pen systems than I’ve been using! When I use a pen on the 
Samsung 700T, I see Pressure values ranging from 0 to 1, but the other three properties have default 
values of 0.5. In theory, the TiltX and TiltY properties indicate how the body of the pen is tilted 
relative to the screen; the Twist property applies only to rectangular pen tips and indicates how the 
rectangular tip is rotated relative to the axes of the screen. 

Throughout this chapter I will be taking Pressure values into account. As you’ll recall in the 
FingerPaint programs, a Polyline was suitable for rendering a connected curve if pressure is ignored, 
but taking pressure into account requires individual Line elements, each with a potentially different 
line thickness, or individual Path elements to mimic a straight line with a varying thickness. 

The code in Simplelnking draws each InkStrokeRenderingSegment (except the first) as a Path 
element with a PathGeometry consisting of a single PothFigure with a single BezierSegment. 

The Stroke property of that Path is a SolidColorBrush created from the Color property of the 
DrawingAttributes property of the InkStroke. The StrokeThickness property is the product of the Size 
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property of the DrawingAttributes for the InkStroke and the Pressure property of the particular Ink- 
StrokeRenderingSegment: 


Project: Simplelnking | File: MainPage.xaml.es (excerpt) 

protected override void OnPointerReleased(Poi nterRoutedEventArgs args) 


// Render the most recent InkStroke 

IReadOnlyList<InkStroke> inkStrokes = inkManager.GetStrokes(); 
InkStroke inkStroke = inkStrokes[inkStrokes.Count - 1]; 


// Create SolidColorBrush used for all segments in the stroke 
Brush brush = new SolidColorBrush (inkStroke.DrawingAttributes.Color); 


// Get the segments 

IReadOnlyList<InkStrokeRenderingSegment> inkSegments = inkStroke.GetRenderingSegments(); 


// Notice loop starts at 1 

for (int i =1; i < inkSegments.Count; i++) 

{ 

InkStrokeRenderingSegment inkSegment = inkSegments[i]; 


// Create a BezierSegment from the points 
BezierSegment bezierSegment = new BezierSegment 
{ 

Pointl = inkSegment.BezierControlPointl, 

Point2 = inkSegment.BezierControlPoint2, 

PointB = inkSegment.Position 

}； 


// Create a PathFigure that begins at the preceding Position 
PathFigure pathFigure = new PathFigure 
{ 

StartPoint = inkSegments[i - 1].Position, 

IsClosed = false, 

IsFilied = false 

}； 

pathFi gure■Segments.Add(bezierSegment); 


// Create a PathGeometry with that PathFigure 
PathGeometry pathGeometry = new PathGeometryO ; 

pathGeometry.Figures.Add(pathFigure); 


// Create a Path with that PathGeometry 
Path path = new Path 
{ 

Stroke = brush, 

StrokeThickness = inkStroke.DrawingAttributes.Size.Width 

inkSegment.Pressure, 

StrokeStartLineCap = PenLineCap .Round, 

StrokeEndLineCap = PenLineCap .Round, 

Data = pathGeometry 
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} 


// Add it to the Grid 
contentGrid.Children.Add(path); 


The for loop starts at 1 in the collection of InkStrokeRenderingSegment objects because the first 
object represents only a start point, whereas each subsequent InkStrokeRenderingSegment is a single 
Bezier curve. In each PathGeometry, the StortPoint in the Path Figure is the Position property from the 
previous InkStrokeRenderingSegment. 

Despite not being able to see what I'm drawing until I lift the pen, I managed this message: 



InkMonager converts a polyline to a series of Bezier curves not just to render a smoother line but 
also to reduce the quantity of data. This particular example consists of five InkStroke objects: two 
for the H, one for the rest of Hello, one for P, and the last for the rest of Pen. You might be inter¬ 
ested in knowing the number of raw polyline segments InkMonager was given and the number of 
InkStrokeRenderingSegment objects it created: 


Stroke 

Polyline 

Segments 

Bezier Segments 

0 

44 

9 

1 

75 

14 

2 

213 

29 

3 

96 

16 

4 

105 

16 
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Even considering that each polyline segment is one point and each Bezier segment (after the first) is 
three points, this is still a significant reduction in data. 

If you want to ignore pressure, you can use a single Path element for the entire InkStroke and 
create the geometry with a single instance of PolyBezierSegment, filling the Points collection with the 
points from each InkStrokeRenderingSegment but using the first one only for setting the Start Point 
property of Path Figure. This alternative approach looks like this: 

// Render the most recent InkStroke 

IReadOnlyList<InkStroke> inkStrokes = inkManager.GetStrokesO; 

InkStroke inkStroke = inkStrokes[inkStrokes.Count - 1]; 


// Create a PolyBezierSegment for all the segments in that stroke 

IReadOnlyList<InkStrokeRenderingSegment> inkSegments = inkStroke.GetRenderingSegments(); 
PolyBezierSegment polyBezierSegment = new PolyBezierSegment (); 

for (int i =1; i < inkSegments.Count; i++) 

{ 

InkStrokeRenderingSegment inkSegment = inkSegments[i]; 

polyBezierSegment.Points.Add(inkSegment.BezierControlPointl); 
polyBezierSegment.Points.Add(inkSegment.BezierControlPoi nt2); 
polyBezierSegment.Points.Add(inkSegment■Position); 

} 

// Create a PathFigure that begins at first point 
PathFigure pathFigure = new PathFigure 
{ 

StartPoint = inkSegments[0].Position, 

IsClosed = false, 

IsFilied = false 

}； 

pathFigure.Segments.Add(poiyBezi erSegment); 


// Create a PathGeometry with that PathFigure 
PathGeometry pathGeometry = new PathGeometry (); 

pathGeometry.Figures.Add(pathFi gure); 


// Create a Path with that PathGeometry 
Path path = new Path 
{ 

Stroke = new SolidColorBrush (inkStroke.DrawingAttributes.Col or), 
StrokeThickness = inkStroke.DrawingAttributes.Size.Width, 
StrokeStartLineCap = PenLineCap. Round, 

StrokeEndLineCap = PenLineCap. Round, 

Data = pathGeometry 


// Add it to the Grid 
contentGrid.Children.Add(path); 
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It’s easy to confirm that InkManager does not attempt to capture the pointer. This is something 
you’ll have to do on your own. However, if the pen drifts outside the control while you're 
accumulating pointer input and you lift the pen, InkManager graciously recovers. It doesn’t raise an 
exception getting a call to ProcessPointerDown if it never finished up its last sequence with a call to 
ProcessPointerUp. 


Erasing and Other Enhancements 


One obvious enhancement to the Simplelnking program is to render a polyline as you’re actually 
drawing with the pen. (That actually qualifies as a minimum standard rather than an enhancement!) 
This polyline is probably either an actual Polyline element if you’re ignoring pen pressure or a 
collection of Line or Path elements if you’re not. But once that logic is implemented, you have a 
choice: You can replace that polyline with the Bezier curves as the stroke is completed, or you can 
leave the polyline on the screen. 

You might be inclined to leave the polyline on the screen if you’ve been experimenting with 
varying the pen pressure with the Simplelnking program. If you look closely at the rendered Bezier 
curves, you might not like what you see, and I don’t blame you. Sometimes it’s easy to see where 
one Bezier curve ends and the next begins because there’s a discontinuity in the line thickness. This 
is particularly noticeable at the beginning and end of a stroke. (In the earlier screen shot, look at the 
ends of the two strokes for the word "Pen .”） 

As you start contemplating this problem, it becomes evident that these Bezier curves should not 
have uniform line thickness. For example, if a stroke consists of four InkStrokeRenderingSegment 
objects with Pressure values of 0.25, 0.5, 0.6, 0.4, the first Bezier curve should have a variable thickness 
starting with a thickness based on 0.25 and increasing to a thickness based on 0.5, the second 
Bezier curve should also have an increasing thickness based on a range from 0.5 to 0.6, and the final 
Bezier curve should decrease in thickness based on 0.6 to 0.4. 

This means that you can't just set BezierSegment properties from the InkStrokeRenderingSegment 
objects. You probably want to use the Bezier curve points and pressure values to synthesize an outline 
of the stroke and then use Path to fill it, much like I did for lines in FingerPaint5. But, obviously, this 
job is much more algorithmically complex for a Bezier spline than for a straight line. 


Another issue: The Simplelnking program renders each new stroke as it’s completed and adds 
the Path elements to the Grid named contentGrid. If you’re drawing polylines as the stroke is being 
created and then replacing them with the Bezier curves, those earlier elements need to be removed 
from the Grid. And, if you implement erasing, at some point you probably need to remove some 
Bezier curves from the Grid, but you won’t be quite sure which ones need to come out unless you tag 
them in some way. 

These two problems suggest that it might be easier just clearing the Children collection of the 
Grid during OnPointerReleosecJ and rendering everything from scratch. It’s usually necessary to do 
this if something has been erased, but you don’t need to do it all the time, particularly if you define 
separate Grid elements for rendering the preliminary lines and rendering the final Bezier curves. 
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The InkManoger has a Mode property of type InkManipulotionMode, an enumeration with three 
members: 

■ Inking 

■ Erasing 

■ Selecting 

The default value is obviously Inking. To enable erasing, you’ll set the property to Erasing during 
On Poin ter Pressed and proceed normally but without rendering anything. Then, in subsequent calls 
to the ProcessPointerilpdote method of InkManoger, whenever the movement of the pen crosses an 
existing stroke, the InkManoger removes that stroke from its collection. 

Although you can re-render all the remaining InkStroke objects during OnPointerReleosed, the 
stroke is actually removed during OnPointerMoved, so you don't need to wait until OnPointerReleosed 
to give the user feedback that a stroke has been erased. 

The new project is called InkAndErase. To simplify the removal of preliminary Line elements 
created during the process of drawing a new stroke, the XAML file contains two sibling Grid elements: 


Project: InkAndErase I File: MainPage.xaml (excerpt) 

<Page … > 

〈Grid Background="Whi te"> 

<Grid Name="contentGri d" /> 

<Grid Name="newLi neGrid" /> 

</Gri d> 

</Page> 

The contentGrid is for the completed strokes rendered with Bezier splines, while the newLineGrid is 
for the Line elements created while a stroke is in progress. This separation makes it easy to get rid of 
those Line segments by just clearing the Children collection of newLineGrid. 


The code-behind file creates an InkDrawingAttributes object and sets it to the InkManoger with 
nondefault values (for the sake of variety), but it also maintains the InkDrawingAttributes object as 
a field for the benefit of the line-drawing code in the On Poin terMo ved override. Because this pro¬ 
gram is performing some processing of pointer input on its own, it defines a Dictionary for storing 
information related to each pointer: 


Project: InkAndErase I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 
{ 

InkManager inkManager = new InkManagerC) ; 

InkDrawingAttributes inkDrawingAttributes = new InkDrawingAttri butes() ; 
bool hasPen; 

Dicti onary<ui nt , Poi nt> pointerDictionary = new Dicti onary<ui nt , Poi nt>(); 


public MainPage() 

{ 

this .InitializeComponent(); 
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// Check if there’s a pen among the pointer input devices 
foreach (Poi nterDevice device in PointerDevi ce.GetPointerDevices()) 
hasPen |= device.PointerDeviceType == PointerDeviceType. Pen; 

// Default drawing attributes 
inkDrawingAttributes.Color = Colors .B1ue; 
inkDrawingAttributes.Size = new Size(6, 6); 
inkManager.SetDefaultDrawingAttributes(inkDrawingAttributes); 


} 

The Bezier rendering code in InkAndErase is virtually identical to that in the previous program, 
but I’ve separated it into two methods to allow the entire assemblage of ink to be redrawn or for 
individual InkStroke objects to be drawn: 

Project: InkAndErase I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

void RenderAl1() 

{ 

contentGrid.Children.ClearO; 


foreach (InkStroke inkStroke in inkManager.GetStrokesO) 
RenderStroke(inkStroke); 


} 


void RenderStroke(InkStroke inkStroke) 

{ 

Brush brush = new SolidColorBrush(i nkStroke.DrawingAttributes.Color); 

IReadOnlyList<InkStrokeRenderingSegment> inkSegments = inkStroke.GetRenderingSegments() 

for (int i =1; i < inkSegments.Count; i++) 

{ 

InkStrokeRenderingSegment inkSegment = inkSegments[i]; 

BezierSegment bezierSegment = new BezierSegment 

{ 

Pointl = inkSegment.BezierControlPoi ntl, 

Point2 = inkSegment.BezierControlPoint2, 

Point3 = inkSegment.Position 

}； 

PathFigure pathFigure = new PathFigure 

{ 

StartPoint = inkSegments[i - 1].Position, 

IsClosed = false, 

IsFilled = false 

}； 

pathFi gure■Segments.Add(bezierSegment); 


PathGeometry pathGeometry = new PathGeometryO ; 

pathGeometry.Figures.Add(pathFi gure); 
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} 


Path path = new Path 

{ 

Stroke = brush, 

StrokeThickness = inkStroke.DrawingAttributes.Size.Width * 

inkSegment.Pressure, 

StrokeStartLineCap = PenLineCap. Round, 

StrokeEndLineCap = PenLineCap. Round, 

Data = pathGeometry 

}； 

contentGrid.Children.Add(path); 


Aside from code to interact with the InkManager object, much of the Pointer event processing 
is very similar to the pressure-sensitive FingerPaint4 program in Chapter 13. The OnPointerPressed 
override is the only place the program checks that the pointer device is a pen. The subsequent Pointer 
overrides use the presence of the pointer ID key in pointerDictionory to determine if a drawing 
operation is in progress. 

The OnPointerPressed override is where the InkMonoger is put into erasing mode based on the 
IsEraser property, which means that the user is touching the screen with the eraser end of the pen. 

A real program would probably have an application bar button to put the InkManager into erasing 
mode for those users who don’t have quite so fancy pens: 


Project: InkAndErase I File: MainPage.xaml.es (excerpt) 

protected override void OnPointerPressed(Poi nterRoutedEventArgs args) 

{ 

if (args.Pointer.PointerDeviceType == PointerDeviceType .Pen || !hasPen) 

{ 

// Get information 

PointerPoint pointerPoint = args.GetCurrentPoi nt(this) ; 
uint id = pointerPoint.Pointerld; 

// Initialize for inking or erasing 
if (!pointerPoint.Properties■IsEraser) 

{ 

inkManager.Mode = InkManipulationMode .Inking; 

} 

else 

{ 

i nkManager .Mode = InkMairi pul ati onMode .Erasing; 

} 


// Give PointerPoint to InkManager 
inkManager.ProcessPointerDown(pointerPoint); 

// Add an entry to the dictionary 

pointerDictionary.Add(args■Pointer.Pointerld, pointerPoint.Position); 
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// Capture the pointer 
CapturePointer(args.Pointer); 

} 

base .OnPointerPressed(args); 

} 

The OnPointerPressed override concludes by capturing the pointer. 

The OnPointerMoved override creates and renders a Line element just like the FingerPaint4 
program, but only if we Ye not erasing. When erasing, the return value from ProcessPointerilpdate is 
checked. If a stroke has been deleted from the collection, this return value is a nonempty Rect object 
indicating the area of the screen that must be repainted. The method responds by re-rendering the 
entire collection of strokes, now missing the deleted stroke: 


Project: InkAndErase | File: MainPage.xaml.es (excerpt) 

protected override void OnPointerMoved(Poi nterRoutedEventArgs args) 

{ 

// Get information 

PointerPoint pointerPoint = args.GetCurrentPoi nt(this) ; 
uint id = pointerPoint.Pointerld; 

if (pointerDictionary.ContainsKey(id)) 

{ 

foreach (Poi nterPoi nt poi nt in args .GetlntermediatePoi nts(this) . ReverseO) 

{ 

// Give PointerPoint to InkManager 

object obj = i nkManager. ProcessPoi nterllpdateCpoi nt); 


if (inkManager.Mode == InkManipulationMode .Erasing) 

{ 

// See if something has actually been removed 
Rect rect = (Rect)obj; 

if (rect.Width != 0 && rect.Height != 0) 

{ 

RenderAl1(); 

} 

} 

else 

{ 

// Render the line 

Point pointl = pointerDictionary[id]; 

Point point2 = pointerPoint.Position; 

Line line = new Line 

{ 

XI = pointl .X ， 

Y1 = pointl.Y, 

X2 = point2.X, 

Y2 = point2.Y, 

Stroke = new SolidColorBrush(i nkDrawingAttributes.Color), 
StrokeThickness = inkDrawingAttributes.Size.Width * 
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pointerPoint.Properties.Pressure ， 
StrokeStartLineCap = PenLineCap. Round, 

StrokeEndLineCap = PenLineCap. Round 

}； 

newLineGrid.Chi 1dren.Add(l i ne); 
pointerDictionary[id] = point2; 

} 

} 

} 

base .OnPointerMoved(args); 


Notice that the Line elements are put into the newLineGrid but the rendering of Bezier strokes 
involves the contentGrid. 

By the time OnPointerReleosed is called, all erasing should have been completed. However, 
any inking operation needs to be completed by rendering the new stroke in the contentGrid and 
removing the preliminary Line elements from the newLineGrid: 


Project: InkAndErase I File: MainPage.xaml.es (excerpt) 

protected override void OnPointerReleased(Poi nterRoutedEventArgs args) 

{ 

// Get information 

PointerPoint pointerPoint = args.GetCurrentPoi nt(this) ; 
uint id = pointerPoint.Pointerld; 

if (pointerDictionary.ContainsKey(id)) 

{ 

// Give PointerPoint to InkManager 
i nkManager. ProcessPoi nterllpCpoi nterPoi nt); 

if (inkManager.Mode == InkManipulationMode .Inking) 

{ 

// Get rid of the little Line segments 
newLineGrid.Children.Cl earO; 

// Render the new stroke 

IReadOnlyList<Inl<Stroke> inkStrokes = inkManager.GetStrokesC); 
InkStroke inkStroke = inkStrokes[inkStrokes.Count - 1]; 
RenderStroke(inkStroke); 

} 

pointerDictionary.Remove(id); 

} 

base .OnPointerReleased(args); 

} 


Because this program has captured the pointer, it should also have a handler for the 
PointerCaptureLost event. It processes this event by deleting the preliminary lines from the 
newLineGrid and re-rendering everything else: 


Project: InkAndErase I File: MainPage.xaml.es (excerpt) 

protected override void OnPointerCaptureLost(Poi nterRoutedEventArgs args) 

{ 

uint id = args.Pointer.Pointerld; 
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if (pointerDictionary.ContainsKeyCid)) 
{ 

pointerDictionary.Remove(i d); 
newLineGrid.Children.Clear(); 
RenderAl1(); 

} 

base .OnPointerCaptureLost(args); 


Selecting Strokes 

The third of the InkManipulationMode members is Selecting. With an electromagnetic pen, you'll want 
to put the InkMonoger into selection mode during a PointerPressed event when the barrel button is 
pressed. The sample program coming up does that, but a real application should also have a program 
option so that the user can manually put the InkManoger into selection mode. 

In this mode, the points that you pass to the ProcessPoin ter Up da te method are interpreted as 
defining an enclosed area. You’ll probably want to render this line but in a way that differentiates it 
from ink input. When this enclosure line has completed, ProcessPointerUp returns a nonempty Red 
value that indicates the bounding rectangle of the selected strokes. If no strokes are selected, the 
Red is empty. If strokes have been selected, the selected InkStroke objects in the collection have their 
Selected property set to true. 

In actual use, selection using this enclosure line seems a little "cranky” to me. Often I have to try 
several times to get it to work. 

It’s also possible to select strokes programmatically using the SelectWithLine or SelectWithPolyLine 
methods of InkMonoger and to manually toggle the Selected property of InkStroke, but I won’t be 
demonstrating these techniques. They allow you to implement your own selection protocol indepen¬ 
dent of InkManoger, in which case you simply don’t make any calls to InkManoger methods while the 
selection operation is in progress. 

After the user has selected one or more InkStroke objects, they should be highlighted in some 
way. You’ll also need to provide program options to do something with these selected items. The 
InkManoger class itself defines methods named DeleteSelected, CopySelectedToClipboard, and 
MoveSelected. This last method translates the strokes with a particular offset from their current 
position. You can also paste strokes from the clipboard into the InkMonoger. 

You’ll probably also want to define application bar controls to change the color or stroke width 
of the selected strokes. You might want these same application bar controls to set default colors and 
stroke widths when strokes are not selected. A lot of the hard stuff here is not the use of InkManoger, 
but the design of the user interface surrounding InkMonoger. 
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The following project is named InkEraseSelect and demonstrates all three modes. Like 
InkAndErase, it contains two Grid elements for rendering ink and preliminary lines: 


Project: InkEraseSelect | File: MainPage.xaml (excerpt) 
<Page … > 

〈Grid Background="Whi te"> 

<Grid Name="contentGrid" /> 

<Grid Name="newLi neGrid" /> 

</Gri d> 


<Page.BottomAppBar> 

<AppBar Name="bottomAppBar" 

Opened="OnAppBarOpened"> 

<StackPanel Orientati on="Hori zontal" 

HorizontalAli gnment="Left"> 


<Button Name="copyAppBarButton" 

Styl e="{StaticResource CopyAppBarButtonStyl e}" 
Cli ck="OnCopyAppBarButtonClick" /> 

<Button Name="cutAppBarButton" 

Styl e="{StaticResource CutAppBarButtonStyle}" 
Cli ck="OnCutAppBarButtonClick" /> 

<Button Name="pasteAppBarButton" 

Styl e=" {StaticResource PasteAppBarButtonStyle} 
Cli ck="OnPasteAppBarButtonCl i ck" /> 


<Button Name="del eteAppBarButton" 

Styl e=" {StaticResource DeleteAppBarButtonStyle} 
Cli ck="OnDel eteAppBarButtonClick" /> 
</StackPanel> 

</AppBar> 

</Page.BottomAppBar> 

</Page> 


The XAML file also has an array of application bar buttons for the standard options Copy, Cut, Paste, 
and Delete. 

The code-behind file starts off the same as in the previous program, except that a Brush is defined 
for coloring the enclosure line for selected items: 


Project: InkEraseSelect I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

InkManager inkManager = new InkManagerO ; 

InkDrawingAttributes inkDrawingAttributes = new InkDrawingAttri butes() ; 
bool hasPen; 

Dictionary<uint, Poi nt> pointerDictionary = new Di ctionary<ui nt , Poi nt>() ; 
Brush selectionBrush = new SolidColorBrush (Colors. Red); 
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public MainPage() 

{ 

this .Ini tializeComponent(); 

// Check if there’s a pen among the pointer input devices 
foreach (Poi nterDevice device in PointerDevice .GetPointerDevices()) 
hasPen |= device.PointerDeviceType == PointerDeviceType .Pen; 

// Default drawing attributes 
inkDrawingAttributes.Color = Colors .B1ue; 
inkDrawingAttributes.Size = new Si ze(6, 6); 
inkManager.SetDefaultDrawingAttributes(inkDrawingAttributes); 


The OnPointerPressed override now also checks for the barrel button. If it’s pressed, the selection 
mode is set. (In a real program, you’ll want an option for setting this mode in the absence of a barrel 
button.) When in selection mode, the program draws a simple enclosure of uniform thickness, so it 
creates a Polyline for this purpose and adds it to newLineGrid: 

Project: InkEraseSelect | File: MainPage.xaml.es (excerpt) 

protected override void OnPointerPressed(Poi nterRoutedEventArgs args) 

{ 

if (args.Poi nter.Poi nterDevi ceType == PointerDeviceType .Pen || !hasPen) 

{ 

// Get information 

PointerPoint pointerPoint = args.GetCurrentPoi nt(this) ; 
uint id = pointerPoint.Pointerld; 

// Initialize for erasing, selecting ， or inking 
if (pointerPoint.Properties.IsEraser) 

{ 

inkManager.Mode = InkManipulationMode. Erasing; 

} 

else if (pointerPoint.Properties.IsBarrelButtonPressed) 

{ 

inkManager.Mode = InkManipulationMode .Selecting; 


// Create Polyline for showing enclosure 
Polyline polyline = new Polyline 
{ 

Stroke = selectionBrush, 

StrokeThickness = 1 

}； 

poiyline.Points.Add(pointerPoint.Position); 
newLineGrid.Children.AddCpolyli ne); 

} 

else 

{ 

inkManager.Mode = InkManipulationMode .Inking; 

} 
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// Give PointerPoint to InkManager 
inkManager.ProcessPointerDownCpointerPoint); 

// Add an entry to the dictionary 

pointerDictionary.Add(args.Pointer.Pointerld, pointerPoint.Position); 

// Capture the pointer 
CapturePointer(args.Pointer); 

} 

base .OnPointerPressed(args); 


In the OnPointerMoved override the erase and inking modes are the same as the previous 
program. For selection, the Polyline is simply continued as in the FingerPaintl program in Chapter 13: 


Project: InkEraseSelect I File: MainPage.xaml.es (excerpt) 

protected override void OnPointerMoved(Poi nterRoutedEventArgs args) 

{ 

// Get information 

PointerPoint pointerPoint = args.GetCurrentPoi nt(this) ; 
uint id = pointerPoint.Pointerld; 

if (pointerDictionary.ContainsKeyCid)) 

{ 

foreach (Poi nterPoi nt poi nt in args .GetlntermediatePoi nts(thi s) . ReverseO) 

{ 

Point pointl = pointerDictionary[id]; 

Point point2 = pointerPoint.Position; 


// Give PointerPoint to InkManager 

object obj = inkManager.ProcessPointerUpdate(point); 

if (inkManager.Mode == InkManipulationMode. Erasing) 

{ 

// See if something has actually been removed 
Rect rect = (Rect)obj; 

if (rect.Width != 0 && rect.Height != 0) 

{ 

RenderAl1(); 

} 

} 

else if (inkManager.Mode == InkManipulationMode .Selecting) 

{ 

Polyline polyline = newLineGrid.Chi 1dren[0] as Polyline; 
poiyline.Points.Add(point2); 

} 

else // inkManager.Mode == 工 nkManipulationMode.Inking 

{ 

// Render the line 
Line line = new Line 
{ 

XI = pointl .X ， 

Y1 = pointl.Y, 

X2 = point2.X, 

Y2 = poi nt2.Y, 

Stroke = new SolidColorBrush (inkDrawingAttributes.Col or), 
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StrokeThickness = inkDrawingAttributes.Size.Wi dth * 

pointerPoint.Properties.Pressure ， 

StrokeStartLineCap = PenLineCap. Round, 

StrokeEndLineCap = PenLineCap. Round 

}； 

newLineGrid.ChiIdren.Add(1ine); 

} 

pointerDictionary[id] = point2; 

} 

} 

base.OnPoi nterMoved(args); 

} 

Of course, in the FingerPointl program there were potentially multiple Polyline elements 
associated with multiple fingers touching the screen, and these multiple Polyline elements are stored 
in a dictionary. Although the InkManager can handle multiple fingers, it cannot handle multiple pens, 
and because selection is enabled only for a pen in this program, it is not possible for multiple Polyline 
elements to exist. A program that allows alternate means of selection involving touch input might 
need to deal with multiple simultaneous selection areas being defined! 


For selection, the OnPointerReleased override removes the Polyline defining an enclosure and calls 
RenderAII. The rendering logic is responsible for rendering selected strokes differently: 


Project: InkEraseSelect | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 


protected override void OnPointerReleased(Poi nterRoutedEventArgs args) 

{ 

// Get information 

PointerPoint pointerPoint = args.GetCurrentPoint(thi s) ; 
uint id = pointerPoint.Pointerld; 

if (pointerDictionary.ContainsKey(id)) 

{ 

// Give PointerPoint to InkManager 
i nkManager. ProcessPoi nterllpCpoi nterPoi nt); 


if (inkManager.Mode == InkManipulationMode. Inking) 

{ 

// Get rid of the little "line segments 
newLineGrid.Children.Clear(); 

// Render the new stroke 

IReadOnlyList<InkStroke> inkStrokes = inkManager.GetStrokesO; 
InkStroke inkStroke = inkStrokes[inkStrokes.Count - 1]; 
RenderStroke(inkStroke); 

} 

else if (inkManager.Mode == InkManipulationMode. Selecting) 

{ 

// Get rid of the encircling "line 
newLineGrid.ChiIdren.Cl ear(); 


// Render everything so selected items are 'identified 
RenderAII(); 
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pointe 「 Dictionary.Remove(id); 


} 

base.OnPoi nterReleased(args); 

} 

protected override void OnPointerCaptureLost(Poi nterRoutedEventArgs args) 
{ 

uint id = args.Pointer.Pointerld; 

if (pointerDictionary.ContainsKey(id)) 

{ 

pointerDictionary.Remove(id); 
newLineGrid.Children.ClearC); 

RenderAl1(); 

} 

base.OnPoi nterCaptureLost(args); 


Here’s what it looks like right before the selection enclosure is completed and the pen lifts up, at 
which point the enclosure line is removed from the screen: 



For this program I’ve separated the rendering logic into three methods. The RenderStroke method 
now calls RenderBeziers, but for selected strokes, it's done twice, the first time with a silver color and a 
thicker pen width so that it surrounds the real stroke: 


Project: InkEraseSelect | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 
{ 

void RenderAl1() 
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contentGrid.Children.Clear(); 


foreach (InkStroke inkStroke in inkManager.GetStrokesO) 

RenderStroke(inkStroke); 

} 

public void RenderStroke (InkStroke inkStroke) 

{ 

Color color = inkStroke.DrawingAttributes.Color; 
double penSize = inkStroke.DrawingAttributes.Size.Width; 

if (inkStroke.Selected) 

RenderBeziers(contentGrid, inkStroke, Colors. Silver, penSize + 24); 

RenderBeziers(contentGrid, inkStroke, color, penSize); 

} 

static void RenderBezi ers(Panel panel, InkStroke inkStroke, Color color, double penSize) 

{ 

Brush brush = new Sol idColorBrush(color) ; 

IReadOnlyList<InkStrokeRenderingSegment> inkSegments = inkStroke.GetRenderingSegmentsC); 


for (int i =1; i < inkSegments.Count; i++) 

{ 

InkStrokeRenderingSegment inkSegment = inkSegments[i]; 


BezierSegment bezierSegment = new BezierSegment 

{ 

Pointl = inkSegment.BezierControlPoi ntl, 

Point2 = inkSegment.BezierControlPoint2, 

Point3 = inkSegment.Position 


PathFigure pathFigure = new PathFigure 

{ 

StartPoint = inkSegments[i - 1].Position, 
IsClosed = false, 

IsFilled = false 

}； 

pathFi gure■Segments.Add(bezierSegment); 


PathGeometry pathGeometry = new PathGeometryC) ; 

pathGeometry.Figures.Add(pathFi gure); 


Path path = new Path 

{ 

Stroke = brush, 

StrokeThickness = penSize * inkSegment.Pressure, 
StrokeStartLineCap = PenLineCap. Round, 
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StrokeEndLineCap = PenLineCap. Round 
Data = pathGeometry 


}； 

panel.Children.Add(path); 



I made RenderBeziers static just to demonstrate exactly what parameters the method needs to 
render a single stroke. 

Here are the selected strokes identified using this technique: 



That’s certainly one way to indicate selected strokes, but you might want to consider others. 

When the application bar is opened, the Opened handler enables or disables the four buttons. 
Three of the buttons are enabled based on the presence of selected strokes in the InkMonoger, the 
Paste button is enabled based on the CanPosteFromClipboarcJ property of InkMonoger: 

Project: InkEraseSelect | File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 
{ 

void OnAppBarOpened (object sender, object args) 

{ 

bool isAnythingSelected = false; 

foreach (InkStroke inkStroke in inkManager.GetStrokesO) 
isAnythingSelected |= inkStroke.Selected; 
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copyAppBarButton.IsEnabled = isAnythingSelected; 
cutAppBarButton.IsEnabled = isAnythingSelected; 
pasteAppBarButton.IsEnabled = inkManager.CanPasteFromClipboard(); 
deleteAppBarButton.IsEnabled = isAnythingSelected; 

} 

void OnCopyAppBarButtonCli ck(object sender, RoutedEventArgs args) 

{ 

inkManager.CopySelectedToClipboard(); 


foreach (InkStroke inkStroke in inkManager.GetStrokesO) 
inkStroke.Selected = false; 

RenderAl1(); 

bottomAppBar.IsOpen = false; 


void OnCutAppBarButtonCli ck(object sender, RoutedEventArgs args) 

{ 

inkManager.CopySelectedToClipboard(); 
inkManager.DeleteSelected(); 

RenderAl1(); 

bottomAppBar.IsOpen = false; 

} 

void OnPasteAppBarButtonCli ck(object sender, RoutedEventArgs args) 

{ 

inkManager.PasteFromCli pboard(new Poi nt()) ; 

RenderAl1(); 

bottomAppBar.IsOpen = false; 


void OnDeleteAppBarButtonCli ck(object sender, RoutedEventArgs args) 

{ 

inkManager.DeleteSelected(); 

RenderAl1(); 

bottomAppBar.IsOpen = false; 


The Copy logic assumes that you don’t want the strokes still selected after they’ve been copied to 
the clipboard. The Cut and Delete handlers don’t need to do something similar because the selected 
strokes are now gone. 

Interestingly, when copying ink to the clipboard, the InkManager also converts the ink to a 
bitmap and an enhanced metafile, so those clipboard formats are available as well for pasting. Some 
programs — most notably, Microsoft Word — can read ink from the clipboard directly, but programs 
that can paste bitmaps from the clipboard are very common. 

All the coordinates in the ink that is copied to the clipboard are normalized to a minimum 
rendering coordinate of (0, 0). This is why the PasteFromClipboard method requires a Point argument. 
If no Point is specified (which is my approach here), the pasted ink appears in the upper-left corner. 

A real program that implements pasting would need to give the user some way to specify where the 
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pasted ink should go on the page. Similar logic might also be used to implement the MoveSelected 
method supported by InkManager. 


The Yellow Pad 


I use a lot of narrow-ruled yellow legal pads when I’m writing a book. It’s my favorite medium for 
taking notes, writing down ideas, sketching out code interrelationships, and figuring out the math 
problems.「m not sure I’ll ever move to an electronic yellow pad for this work, but 111 give the 
alternative a fair chance by coding an application that lets me try it out 


The YellowPad program is not commercial grade, but it does have a few more features than the 
programs presented so far in this chapter: 

YellowPad supports multiple pages viewable in a FlipView control. Thus, you can go from page to 
page with a sweep of your finger. The program ensures that the FlipView never reaches the end of the 
collection by always creating a new page when that’s about to happen. 


YellowPad also demonstrates the LoadAsync and SaveAsync methods defined by InkManager by 
saving the contents of all pages in local application storage during the Suspending event and loading 
them the next time the program is run. 

YellowPad has the application bar items you’ve just seen and adds items that let you set a pen 
width and color for the current page or for selected strokes. 

To consolidate some of this logic away from the user interface, I defined a class named 
InkFileManoger. If InkManager were not sealed, InkFileManoger would derive from InkManager, but 
instead InkFileManoger instantiates an InkManager as well as a default InkDrowingAttributes object 
and exposes those as public properties. It also includes a method to update the InkManager with new 
drawing attribute values: 


Project: YellowPad I File: lnkFileManager.es (excerpt) 

public class InkFi1eManager 
{ 

string id; 


public InkFi1eManager (stri ng id) 

{ 

this •id = id; 

this .InkManager = new InkManagerO ; 

this .InkDrawingAttributes = new InkDrawingAttH butes() ; 


public InkManager InkManager 
{ 

private set; 
get; 

} 
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public InkDrawingAttributes InkDrawingAttributes 


private set; 
get; 


public void UpdateAttributes() 

{ 

this. InkManager.SetDefaultDrawingAttributes (this. InkDrawingAttributes); 

} 


InkFileMonager also contains a couple small routines involving selection: 

Project: YellowPad I File: lnkFileManager.es (excerpt) 

public cl ass InkFi1eManager 


public bool IsAnythingSelected 

{ 

get 

{ 

bool isAnythingSelected = false; 

foreach (InkStroke inkStroke in this .InkManager.GetStrokesO) 
isAnythingSelected |= inkStroke.Selected; 

return isAnythingSelected; 

} 

} 


public void UnselectAl1() 

{ 

if (IsAnythingSelected) 

{ 

foreach (InkStroke inkStroke in this .InkManager.GetStrokesO) 
inkStroke.Selected = false; 

RenderAl1(); 



} 

I have also moved all the Bezier rendering logic into this file. Aside from the InkManager object 
itself, the only thing the rendering logic needs is a Panel to which to add Path elements. This vital 
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information is provided through a public property named RenderTorget. The rendering of selected 
strokes is the same as in the previous program: 

Project: YellowPad I File: lnkFileManager.es (excerpt) 

public class InkFi1eManager 

{ 

public Panel RenderTarget 

{ 

set ; 
get; 

} 


public void RenderAl1() 

{ 

thi s. RenderTarget.Children.Clear(); 


foreach (InkStroke inkStroke in this .InkManager.GetStrokesO) 
RenderStroke(inkStroke); 


public void RenderStroke (InkStroke inkStroke) 

{ 

Color color = inkStroke.DrawingAttributes.Color; 
double penSize = inkStroke.DrawingAttributes.Size.Width; 

if (inkStroke.Selected) 

RenderBeziers (this. RenderTarget, inkStroke, Colors. Silver, penSize + 24); 

RenderBezi ers(thi s .RenderTarget, inkStroke, color, penSize); 

} 

static void RenderBezi ers(Panel panel, InkStroke inkStroke, Color color, double penSize) 

{ 

Brush brush = new SoTidColorBrush(color) ; 

IReadOnlyList<InkStrokeRenderingSegment> inkSegments = inkStroke.GetRenderingSegmentsC); 


for (int i =1; i < inkSegments.Count; i++) 

{ 

InkStrokeRenderingSegment inkSegment = inkSegments[i]; 


BezierSegment bezierSegment = new BezierSegment 

{ 一 
Pointl = inkSegment.BezierControlPointl, 

Point2 = inkSegment.BezierControlPoint2, 

Point3 = inkSegment.Position 

}； 

PathFigure pathFigure = new PathFigure 

{ 

StartPoint = inkSegments[i - 1].Position, 
IsClosed = false, 

IsFilled = false 

}； 

pathFigure■Segments.Add(bezierSegment); 
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PathGeometry pathGeometry = new PathGeometryC) ; 

pathGeometry.Figures.Add(pathFi gure); 


Path path = new Path 

{ 

Stroke = brush, 

StrokeThickness = penSize * inkSegment.Pressure, 
StrokeStartLineCap = PenLineCap. Round, 
StrokeEndLineCap = PenLineCap .Round, 

Data = pathGeometry 

}； 

panel.Children.Add(path); 



Finally, InkFileMonoger has two public methods that help justify the "File” part of its name. The 
LoodAsync method loads previously saved ink and settings, or it sets default values if the page 
is newly created. The Save A sync method saves the current contents of the InkManoger to local 
application storage, as well as the pen thickness and color currently associated with that InkMonager. 
Both make use of an ID string originally passed to the constructor and saved as a field. This ID string is 
unique for every InkFileManager object the program maintains. As you’ll see, it is simply an index (0, 

1, 2, and so forth) converted to a string. 


Project: YellowPad I File: lnkFileManager.es (excerpt) 

public class InkFileManager 


bool isLoaded; 


public async Task LoadAsyncO 

{ 

if (isLoaded) 
return ; 

// Load previously saved ink 

StorageFolder storageFolder = ApplicationData. Current.LocalFolder; 
try 

StorageFi1e storageFile = 

await storageFolder.GetFileAsync(" Page" + id + "•ink"); 

using (IRandomAccessStream stream = 

await storageFile.OpenAsync(Fi1 eAccessMode. Read)) 

{ 

await this .InkManager.LoadAsync(stream.GetInputStreamAt(O)); 

} 

} 

catch 

{ 
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} 


// Do nothing if an exception occurs 


// Load saved settings 

IPropertySet appData = ApplicationData. Current.LocalSettings.Values; 

// Pen size setting 
double penSize = 4; 

if (appData.ContainsKey ("PenSize" + id)) 

penSize = (doubl e) appData ["PenSize" + id]; 

this .InkDrawingAttributes.Size = new Si ze(penSize, penSize); 

// Color setting 

if (appData.Contai nsKey("Color + i d")) 

{ 

byte[] argb = (byte[])appData["Color + id"] ; 
this ■InkDrawingAttributes.Color = 

Color. FromArgb(argb[0], argb[l], argb[2], argb[3]); 

} 

// Set default drawing attributes 
UpdateAttributes(); 
isLoaded = true ; 

} 

public async Task SaveAsyncO 

{ 

if (!isLoaded) 
return ; 

// Save the ink 

StorageFolder storageFolder = ApplicationData. Current.LocalFolder; 
try 

StorageFi1e storageFile = 

await storageFolder.CreateFi1 eAsync("Page" + id + ".ink" , 

CreationCol1isionOption .ReplaceExisting); 

using (IRandomAccessStream stream = 

await storageFile.OpenAsync (Fi_l eAccessMode. ReadWrite)) 

{ 

await this .InkManager.SaveAsync(stream.GetOutputStreamAt(0)); 

} 

} 

catch 

{ 

// Do nothing if an exception occurs 

} 

// Save settings 

IPropertySet appData = ApplicationData. Current.LocalSettings.Values; 

// Save pen size 

appData["PenSi ze" + id] = this .InkDrawingAttributes.Size.Width; 
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// Save color 

Color color = this .InkDrawingAttributes.Color; 
byte[] argb = { color.A, color.R, color.G, color.B }; 
appData["Color" + id] = argb; 


In the YellowPad program, each InkFileManoger is associated with a User Control derivative named 
YellowPadPoge. Here's the XAML file for that class, including the visual mimicking of a legal pad with a 
yellow background and two red vertical lines toward the left of the page. 


Project: YellowPad I File: YellowPad Page.xaml 
<UserControl 

x:Cl ass="Yel 1owPad.Yel1owPadPage" 

xml ns="http: //schemas.microsoft.com/winfx/2006/xaml/presentati on" 
xml ns : x="http://schemas.microsoft.com/winfx/2006/xaml" 
xml ns : 1 ocal="usi ng:Yel1owPad”> 


<Grid> 

<Viewbox> 

〈Grid Name="sheetPanel " 

Width="816" Height="1056" 

Background="#FFFF80"> 

〈Line Stroke="Red" Xl="132" Y1="0" X2="132" Y2="1056" /> 
<Line Stroke="Red" Xl="138" Y1="0" X2="138" Y2="1056" /> 

<Grid Name="contentGri d" /> 

<Grid Name="newLi neGrid" /> 

</Grid> 

</Viewbox> 

</Gri d> 

</UserContro1 > 


The control incorporates a Viewbox so that it adapts to any size window. 

As you can guess from seeing the names of the two inner Grid elements, the code-behind file 
handles all the pointer input. However, I discovered that trying to make this program run on a nonpen 
device was problematic. Keep in mind that instances of YellowPodPage are in a FlipView, and the 
FlipView wants its own touch input for changing the selected items. I decided to eliminate the logic 
that allows the program to run without a pen. YellowPad insists that you be using a real pen. 

The YellowPodPage constructor is responsible for drawing the blue rule lines on the page: 

Project: YellowPad I File: YellowPadPage.xaml.es (excerpt) 

public YellowPadPage() 

{ 

this. InitializeComponentC); 

// Draw horizontal lines in blue 

Brush blueBrush = new SolidColorBrush(Colors. Blue); 
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for (int y = 120; y < sheetPanel.Height; y += 24) 
sheetPanel.Children.Add (new Line 
{ 

XI = 0 ， 
yi = y, 

X2 = sheetPanel.Width ， 

Y2 = y, 

Stroke = blueBrush 

}); 

} 

The YellowPadPoge control also defines a new dependency property of type InkFileManoger. 
Here’s the overhead: 

Project: YellowPad | File: YellowPadPage.xaml.es (excerpt) 

public sealed partial class YellowPadPage : UserControl 

{ 

static readonly DependencyProperty i nkFi1eManagerProperty = 

DependencyProperty .Regi ster("InkFi1 eManager" , 

typeof (InkFi1eManager) , 
typeof (Yel1owPadPage) , 

new PropertyMetadata(nul1 , OnlnkFi1eManagerChanged)); 


// Overhead for InkFi1eManager dependency property 
public static DependencyProperty InkFileManagerProperty 
{ 

get { return inkFi1eManagerProperty; } 

} 

public InkFi1eManager InkFi1eManager 

{ 

set { SetValue(InkFi1eManagerProperty, value); } 

get { return (InkFi1 eManager)GetValue(InkFi1eManagerProperty); } 

} 

static void OnlnkFileManagerChanged(DependencyObject obj, 

DependencyPropertyChangedEventArgs args) 

{ 

(obj as Yel1owPadPage) .OnlnkFileManagerChanged(args); 

} 

async void OnlnkFileManagerChanged(DependencyPrope rtyChangedEventArgs args) 

{ 

contentGrid.Children.Clear(); 
newLineGrid.Children.Clear(); 

if (args.NewValue != null) 

{ 

await this .InkFi1eManager.LoadAsyncC); 

this .InkFi1eManager.RenderTarget = contentGrid; 

this .InkFi1eManager.RenderAl1(); 

} 
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When this InkFileMonoger property is set to a new InkFileMonager instance, the property-changed 
handler calls LoadAsync to load any existing ink and settings, sets the RenderTorget to its own 
contentGrid, and then has the InkFileMonoger render all the ink that existed previously. 

The remainder of YellowPadPoge assumes this InkFileMonoger property has already been set and is 
dedicated to processing the Pointer events. This logic here is virtually the same as what you’ve seen in 
the previous program, except that it uses the InkFileMonoger property to obtain the InkMonoger and 
InkDrawingAttributes objects associated with this page and for rendering the strokes: 


Project: YellowPad I File: YellowPadPage.xaml.es (excerpt) 


public sealed partial class YellowPadPage 

{ 


UserControl 


Dictionary<uint, Poi nt> pointerDictionary = new Dictionary<uint, Poi nt>() ; 
Brush selectionBrush = new SolidColorBrush (Colors. Red); 

protected override void OnPointerPressed(Poi nterRoutedEventArgs args) 

{ 

if (args.Pointer.PointerDeviceType == PointerDeviceType. Pen) 

{ 

// Get information 

PointerPoint pointerPoint = args.GetCurrentPoint(sheetPanel); 
uint id = pointerPoint.Pointerld; 

InkManager inkManager = this. InkFi1eManager.InkManager; 

// Initialize for inking, erasing, or selecting 
if (pointerPoint.Properties■IsEraser) 

{ 

inkManager.Mode = InkManipulationMode. Erasing; 
this. InkFi1eManager.UnselectAll(); 

} 

else if (pointerPoint.Properties.IsBarrel ButtonPressed) 

{ 

inkManager.Mode = InkManipulationMode. Selecting; 

// Create Polyline for showing enclosure 
Polyline polyline = new Polyline 
{ 

Stroke = selectionBrush, 

StrokeThickness = 1 

}； 

polyline.Points.Add(pointerPoint.Position); 
newLineGrid.Chi 1dren.Add(poiyline); 

} 

else 

{ 

inkManager.Mode = InkManipulationMode. Inking; 
this. InkFileManager.UnselectAll(); 


// Give PointerPoint to InkManager 
inkManager.ProcessPointerDown(poi nterPoi nt); 

// Add an entry to the dictionary 

pointerDictionary.Add(args■Pointer■Pointerld, poi nterPoi nt.Posi ti on); 
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// Capture the pointer 

this .CapturePointer(args.Pointer); 

} 

base .OnPointerPressed(args); 

} 


protected override void OnPointerMoved(Poi nterRoutedEventArgs args) 

{ 

// Get information 

PointerPoint pointerPoint = args.GetCurrentPoint(sheetPanel); 
uint id = pointerPoint.Pointerld; 

InkManager inkManager = this .InkFileManager.InkManager; 

InkDrawingAttributes inkDrawingAttributes = 

this .InkFi1eManager.InkDrawingAttributes; 


if (pointerDictionary.ContainsKey(id)) 

{ 

foreach (Poi nterPoi nt poi nt i n args .GetIntermedi atePoi nts(sheetPanel) . ReverseO) 

{ 

Point pointl = pointerDictionary[id]; 

Point point2 = pointerPoint.Position; 


// Give PointerPoint to InkManager 

object obj = inkManager. ProcessPoi nterl)pdate(point); 

if (inkManager.Mode == InkManipulationMode .Erasing) 

{ 

// See if something has actually been removed 
Rect rect = (Rect)obj; 

if (rect.Width != 0 && rect.Height != 0) 

{ 

this. InkFi1eManager.RenderAl1(); 

} 

} 

else if (inkManager.Mode == InkManipulationMode .Selecting) 

{ 

Polyline polyline = newLineGrid.Chi 1dren[0] as Polyline; 
polyline.Points.Add(point2); 

} 

else // inkManager.Mode == InkManipulationMode.Inking 

{ 

// Render the line 
Line line = new Line 
{ 

XI = pointl.X, 

Y1 = pointl.Y, 

X2 = point2.X, 

Y2 = poi nt2.Y, 

Stroke = new SolidColorBrush(i nkDrawingAttributes.Color), 
StrokeThickness = inkDrawingAttributes■Size.Width * 

pointerPoint.Properties.Pressure, 
StrokeStartLineCap = PenLineCap. Round, 

StrokeEndLineCap = PenLineCap .Round 

}； 

newLineGrid.Chi 1dren.Add(1ine); 
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pointerDictionary[id] = point2; 

} 

} 

base.OnPoi nterMoved(args); 


protected override void OnPointerReleased(Poi nterRoutedEventArgs args) 

{ 

// Get information 

PointerPoint pointerPoint = args.GetCurrentPoint(sheetPanel); 
uint id = pointerPoint.Pointerld; 

InkManager inkManager = this .InkFileManager.InkManager; 

if (pointerDictionary.ContainsKey(id)) 

{ 

// Give PointerPoint to InkManager 
i nkManager. ProcessPoi nterllpCpoi nterPoi nt); 


if (inkManager.Mode == InkManipulationMode .Inking) 

{ 

// Get rid of the little "line segments 
newLineGrid.Children.Clear(); 

// Render the new stroke 

IReadOnlyList<InkStroke> inkStrokes = inkManager.GetStrokesO; 
InkStroke inkStroke = inkStrokes[inkStrokes.Count - 1]; 
this. InkFi1eManager.RenderStroke(i nkStroke); 

} 

else if (inkManager.Mode == InkManipulationMode .Selecting) 

{ 

// Get rid of the enclosure line 
newLineGrid.Children.Clear(); 

// Render everything so selected items are identified 
this. InkFi1eManager.RenderAl1(); 

} 

pointerDictionary.Remove(id); 

} 

base.OnPoi nterReleased(args); 


protected override void OnPointerCaptureLost(Poi nterRoutedEventArgs args) 

{ 

uint id = args.Pointer.Poi nterld; 

if (pointerDictionary.ContainsKey(id)) 

{ 

pointerDictionary.Remove(id); 
newLineGrid.Children.Clear(); 
this .InkFi1eManager.RenderAl1(); 

} 

base.OnPoi nterCaptureLost(args); 
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YellowPadPage gets an instance of InkFileManager through a data binding. The FlipView control in 
Main Page contains a collection of InkFileManager objects — one for each page — so the ItemTemplate 
for the FlipView is dominated (in appearance though not markup) with a YellowPadPage with a 
binding to the item in the control’s ItemsSource collection: 

Project: YellowPad I File: MainPage.xaml (excerpt) 

<Page … > 

<Page.Resources 〉 

<local : IndexToPageNumberConverter x:Key="i ndexToPageNumber" /> 

</Page.Resources 〉 


<Grid Background="{Stati cResource ApplicationPageBackgroundThemeBrush}"> 
〈FlipView Name="fl ipView" 

Selecti onChanged="OnFl ipViewSelectionChanged"> 

<F1ipView.ItemTempl ate> 

<DataTemplate> 

<Grid HorizontalAli gnment="Center" 

VerticalAl ignment="Center"> 


〈 local : YellowPadPage InkFi leManager="{Binding}" /> 

<TextBlock Name="pageNumTextBl ock" 

HorizontalAli gnment="Ri ght" 

VerticalAli gnment="Top" 

FontSize="12" 

Foreground=" Black" 

Margin="6" 

Text="{Binding ElementName=fl ipView, 

Path=Sel ectedlndex, 

Converter={StaticResource indexToPageNumber}}" /> 

</Grid> 

</DataTemplate> 

</FlipView.ItemTemplate> 

</FlipView> 

</G「i d> 


<Page.BottomAppBar> 

</Page.BottomAppBar> 

</Page> 

The TextBlock defined in the DatoTemplote along with YellowPadPage displays the current page 
number. This binding on the Text property references an ad hoc binding converter that converts a 
zero-based index to a text label: 


Project: YellowPad | File: lndexToPageNumberConverter.es 
using System; 

using Windows.UI.Xaml.Data; 

namespace YellowPad 

{ 

public cl ass IndexToPageNumberConverter : IValueConverter 
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public object Convert(object value, Type targetType, object parameter, string language) 

{ 

return String . Format("Page {0}" , (int) value + 1); 

} 


public object ConvertBack (object value, Type targetType, object parameter, string 1 ang) 

{ 

return value; 

} 



As you’ve seen, each InkFileMonoger instance saves and restores application settings associated 
with that page, including the ink content of that page. The Main Page code saves and restores settings 
associated with the application itself. This is just two integer items: the number of pages (which is the 
number of items in the collection of InkFileMonoger objects), and the current page index (which is the 
Selectedlndex property of the FlipView): 


Project: YellowPad I File: MainPage.xaml.es (excerpt) 


public sealed partial class MainPage : Page 


ObservableCol1ection<InkFi1eManager> inkFileManagers = 

new ObservableCol1ection<InkFi1 eManager>() ; 


public MainPage() 


this. InitializeComponent(); 

Loaded += OnMainPageLoaded; 

Application .Current.Suspending += OnApplicationSuspending; 


void OnMainPageLoaded (object sender, RoutedEventArgs args) 

{ 

// Load application settings 

IPropertySet appData = ApplicationData. Current.LocalSettings.Values; 

// Get the page count 
int pageCount = 1; 

if (appData.ContainsKey(" PageCount")) 

pageCount = (i nt)appData["PageCount"] ; 

// Create that many InkFileManager objects 
for (int i =0; i < pageCount; i++) 

inkFi1eManagers .Add(new InkFi1 eManager(i .ToString())); 

// Set the collection to the FIipView 
flipView.ItemsSource = inkFi1eManagers; 

// Set the Selectedlndex of the PageView 
if (appData.Contai nsKeyC'Pagelndex")) 

flipView.Selectedlndex = (i nt)appData["PageIndex"] ; 

} 
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async void OnApplicationSuspendi ngCobject sender, SuspendingEventArgs args) 

{ 

SuspendingDeferral deferral = args.SuspendingOperation.GetDeferral(); 

// Save all the InkFi1eManager contents 

foreach (InkFi 1eManager inkFi1eManager in inkFi1eManagers) 
await inkFi 1 eManager.SaveAsyncO ; 


// Save the page count 
IPropertySet appData = 
appData["PageCount"] = 
appData["PageIndex"] = 


and current page index 

ApplicationData. Current.LocalSettings.Values; 
inkFi1eManagers.Count; 
flipView.Selectedlndex; 


deferral .CompleteO; 

} 


void OnFlipViewSelectionChanged (object sender, SelectionChangedEventArgs args) 

{ 

// If at the end of the FlipView, add another item! 
if (f1ipView.Selectedlndex == f1ipView.Items.Count - 1) 

inkFi1eManagers.Add (new InkFi1eManager (flipView.Items.Count.ToString())); 

} 

} 


Notice that the Loaded handler creates all the InkFileManager objects for the current number 
of pages, but the InkFileManager constructor does nothing beyond creating InkManoger and 
In kD ro wing A ttributes instances. In particular, it doesn't yet load in any previously saved ink. This 
happens later when the InkFileManager instance is actually bound to a YellowPodPage. Keep in mind 
that the items panel for the FlipView is a VirtuolizingStackPonel, which creates visual trees for the 
items only as they’re needed. This means that the loading of previously saved ink is spread out over 
a longer period of time and occurs as the user is actively flipping through the various pages. Some 
pages might not be loaded at all, and those that aren’t loaded don’t need to be saved again. 

The remainder of the program is dedicated to handling buttons on the application bar, including 
the flawed Paste logic that you’ve already seen. In addition to the four clipboard-related buttons, the 
application bar also includes two very similarly templated ComboBox controls, one for the pen width 
and the other for the pen color: 


Project: YellowPad | File: MainPage.xaml (excerpt) 

<AppBar Name="bottomAppBar" 

Opened="OnAppBarOpened"> 

<Gri d> 

<StackPanel Orientati on="Hori zontal" 

HorizontalA1i gnment="Left"> 

〈Button Name="copyAppBarButton" 

Style="{StaticResource CopyAppBarButtonStyle} 
Cli ck="OnCopyAppBarButtonClick" /> 
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〈Button Name="cutAppBarButton" 

Style="{StaticResource CutAppBarButtonStyl e}" 

Cli ck="OnCutAppBarButtonClick" /> 

〈Button Name=" pasteAppBarButton" 

Styl e="{StaticResource PasteAppBarButtonStyl e}" 
Cli ck="OnPasteAppBarButtonCl ick" /> 

〈Button Name="del eteAppBarButton" 

Style="{StaticResource DeleteAppBarButtonStyl e} 
Cli ck="OnDel eteAppBarButtonClick" /> 
</StackPanel> 


<StackPanel Orientati on="Hori zontal" 

HorizontalA1i gnment="Ri ght"> 

<ComboBox Name="penSi zeComboBox" 

Selecti onChanged="OnPenSi zeComboBoxSelectionChanged" 
Width="200" 

Margin="20 0"> 

<x : Doubl e>2</x: Double> 

<x : Doubl e>3</x: Doubl e> 

<x : Doubl e>4</x: Doubl e> 

<x : Doubl e>5</x: Doubl e> 

<x : Doubl e>7</x: Double> 

<x : Doubl e>10</x : Double> 


<ComboBox.ItemTemplate> 

<DataTemplate> 

〈Path StrokeThi ckness="{Bindi ng}" 

Stroke="Black" 

StrokeStartLi neCap="Round" 

StrokeEndLi neCap="Round" 

Data="M 0 0 C 50 20 100 0 150 20" /> 
</DataTemplate> 

</ComboBox.ItemTemplate> 

</ComboBox> 

<ComboBox Name="col orComboBox" 

Selecti onChanged="0nCol orComboBoxSelectionChanged" 
Width="200" 

Margin="20 0"> 

<Col or>#FF0000</Col or> 

<Col or>#800000</Col or> 

<Col or>#FFFF00</Col or> 

<Col or>#808000</Col or> 

<Col or>#00FF00</Col or> 

<Col or>#008000</Col or> 

<Col or>#00FFFF</Col or> 

<Col or>#008080</Col or> 

<Col or>#0000FF</Col or> 

<Col or>#000080</Col or> 

<Color>#FF00FF</Color> 

<Col or>#800080</Col or> 

<Color>#C0C0C0</Color> 
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<Col or>#808080</Col or> 
<Col or>#404040</Col or> 
<Col or>#000000</Col or> 


<ComboBox.ItemTemplate> 

<DataTemplate> 

<Path StrokeThi ckness="6" 

StrokeStartLi neCap="Round" 

StrokeEndLi neCap="Round" 

Data="M 0 0 C 50 20 100 0 150 20"> 

<Path.Stroke> 

<SolidColorBrush Color="{Bindi ng}" /> 

</Path.Stroke> 

</Path> 

</DataTemplate> 

</ComboBox.ItemTemplate> 

</ComboBox> 

</StackPanel> 

</Gri d> 

</AppBar> 

To keep the program simple , 丨 have not implemented any adjustments for portrait or snapped 
modes. These modes result in overlapping buttons and combo boxes. 

The application bar items are all applicable to the current page displayed in the FlipView. 
Moreover, the two ComboBox controls might be applicable to the page — that is, to the default 
InkDrawingAttributes object associated with the current InkFileMonoger for this page — or to 
selected items on the page. When the application bar is opened, these controls must be initialized 
appropriately: 


Project: YellowPad I File: MainPage.xaml.es (excerpt) 

void OnAppBarOpened (object sender, object args) 

{ 

InkFi1eManager inkFileManager = (InkFi1eManager)fl ipView.Selectedltem; 

copyAppBarButton.IsEnabled = inkFi1eManager.IsAnythingSelected; 
cutAppBarButton.IsEnabled = inkFi1eManager.IsAnythingSelected; 
pasteAppBarButton.IsEnabled = inkFi1eManager.InkManager.CanPasteFromClipboard(); 
deleteAppBarButton.IsEnabled = inkFi1eManager.IsAnythingSelected; 

if (!inkFi1eManager.IsAnythingSelected) 

{ 

// Set initial selected item 

Size size = inkFi1eManager.InkDrawingAttributes.Size; 
penSizeComboBox.Selectedltem = (size.Width + size.Height) / 2; 
colorComboBox.Selectedltem = inkFi1eManager.InkDrawingAttributes.Color; 

} 

else 

{ 

penSizeComboBox.Selectedltem = null; 
colorComboBox.Selectedltem = null; 
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A more sophisticated version of this method would loop through the selected strokes and 
determine whether they all had the same color or width. If so, those values could be used to initialize 
the two ComboBox controls. As it is now, each ComboBox is given no selected value when strokes are 
selected. 

The handling of the four clipboard items is very similar to the previous program except that the 
InkManoger must be accessed through the InkFileManager available from the Selectedltem property 
of the FlipView: 

Project: YellowPad I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

void OnCopyAppBarButtonCli ck(object sender, RoutedEventArgs args) 

{ 

InkFileManager inkFi1eManager = (InkFi1 eManager)fl ipView.Selectedltem; 
inkFi1eManager.InkManager.CopySelectedToClipboard(); 

foreach (InkStroke inkStroke in inkFi 1 eManager.InkManager.GetStrokesO) 
inkStroke.Selected = false; 

inkFi1eManager.RenderAl 1(); 
bottomAppBar.IsOpen = false; 

} 

void OnCutAppBarButtonCli ck(object sender, RoutedEventArgs args) 

{ 

InkFi1eManager inkFi1eManager = (InkFi1eManager) flipView.Selectedltem; 
inkFi1eManager.InkManager.CopySelectedToCl i pboard(); 
i nkFi1eManager.InkManager.DeleteSelected(); 
i nkFi1eManager.RenderAl1(); 
bottomAppBar.IsOpen = false; 

} 

void OnPasteAppBarButtonCli ck(object sender, RoutedEventArgs args) 

{ 

InkFi 1 eManager inkFi1eManager = (InkFi1eManager) flipView.Selectedltem; 
inkFi1eManager.InkManager.PasteFromClipboard(new Poi nt()); 
inkFi1eManager.RenderAl 1(); 
bottomAppBar.IsOpen = false; 

} 

void OnDeleteAppBarButtonCli ck(object sender, RoutedEventArgs args) 

{ 

InkFi 1eManager i nkFi 1 eManager = (InkFi1eManager) flipView.Selectedltem; 
inkFi1eManager.InkManager.DeleteSelected(); 
inkFi1eManager.RenderAl 1(); 
bottomAppBar.IsOpen = false; 
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The processing of the two Com bo Box controls is very similar. In both cases, either the 
In kD ro wing A ttributes object of the InkFileMonoger is given new values for future drawing or the 
selected strokes are updated with new values: 

Project: YellowPad I File: MainPage.xaml.es (excerpt) 

public sealed partial class MainPage : Page 

{ 

void OnPenSizeComboBoxSelectionChanged (object sender, SelectionChangedEventArgs args) 

{ 

if (penSizeComboBox.Selectedltem == null) 
return ; 


InkFileManager inkFileManager = (InkFi1 eManager)fl ipView.Selectedltem; 


double penSize = (double) penSizeComboBox.Selectedltem; 
Size size = new SizeCpenSize, penSize); 


if (!inkFi1eManager.IsAnythingSelected) 

{ 

inkFi1eManager.InkDrawingAttributes.Size = size; 
inkFi1eManager.UpdateAttributes(); 

} 

else 

{ 

foreach (InkStroke inkStroke in inkFileManager.InkManager.GetStrokesO) 
if (inkStroke.Selected) 

{ 

InkDrawingAttributes drawingAttrs = inkStroke.DrawingAttributes; 
drawingAttrs.Size = size; 
inkStroke.DrawingAttributes = drawingAttrs; 

} 

inkFi1eManager.RenderAl1(); 

} 

} 

void OnColorComboBoxSelectionChanged (object sender, SelectionChangedEventArgs args) 

{ 

if (colorComboBox.Selectedltem == null) 
return ; 

InkFi1eManager inkFi1eManager = (InkFileManager) flipView.Selectedltem; 

Color color = (Col or) colorComboBox.Selectedltem; 


if (!inkFi1eManager.IsAnythingSelected) 

{ 

inkFi1eManager.InkDrawingAttributes.Color = color; 
inkFi1eManager.UpdateAttributes(); 

} 

else 

{ 
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} 


foreach (InkStroke inkStroke in inkFi1eManager.InkManager.GetStrokes()) 
if (inkStroke.Selected) 

{ 

InkDrawingAttributes drawingAttrs = inkStroke.DrawingAttributes; 
drawingAttrs.Color = color; 
inkStroke.DrawingAttributes = drawingAttrs; 

} 

inkFi1eManager.RenderAl1(); 


This program certainly has some flaws. For example, you can set color and pen width attributes for 
the current page or for selected strokes, but you can’t set values that apply to all new pages created 
in the future. Each new page starts out with defaults hard-coded in the InkFileMonoger class. 

What the program really needs is a GridView control that displays all the pages as thumbnails and 
lets you move them around, or select them for deletion or printing, or even group them. 

But that’s the nature of software. It’s never really finished because it never needs to be finished, 
and it’s quite unlike books in that respect. 
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AccumulateDelta method, 675 
Action delegates, 214 

Action<object> delegate, 214 
ActualHeight property, 85-86 
ActualWidth property, 85-86 
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animation classes, 91 
AnimationEaseGrapher project, 351-358 
code-behind file, 354-357 
XAMLfile, 352-354 


animations 


animations, 329-376 

all-XAML animations, 359-363 

of attached properties, 347-350 

autoreversing, 335 

in background threads, 330 

basic animations, 330-333 

on button visual states, 516 

code, defining in, 338-340 

of colors, 92-96 

completion, notification of, 338 

CompositionTarget.Rendering events, 91-92 

control appearance, changing, 329 

of custom classes, 364-367 

of dependency properties, 94-95 

double animations, 340-347 

duration, 332, 369 

easing functions, 336-337, 350-359 

of Ellipse class, 341-342 

event handling, 89-96 

of fill, 371-372 

flicker-free, 83 

frame-based animations, 330 
on gradients, 702 
heap allocations and, 94 
jiggling, 386-387 
key frame animations, 367-371 
linear, 329, 333-336, 350 
manual, 329 
of Object class, 371-372 
objects, creating in XAML file, 93-94 
on Opacity property, 345 
predefined, 373-376 
repeating, 335-336 
restarting, 333, 334 
in secondary threads, 331 
speed, 330 
speeding up, 338 
springiness, 337 
target, 330, 339 
target property, releasing, 334 
time-based, 330 
transfer functions, 351-358 
triggering, 387, 436-437 
triggering in Loaded event, 339, 341, 359-363 
Triggers section, defining in, 372 
in user-interface thread, 331 
values outside From and To settings, 357-358 
of visibility, 371-372 
on visual state elements, 513 
Windows.Ul.Xa ml. Media. Animation 
namespace, 329-330 
zooming, 998 
anonymous methods, 288 


antialiasing, 758 

AppBarButtonStyle style, 271-276 
Setter object, 271 
TargetType, 283 

AppBar class, 261, 268-271. See also application bars 
BottomAppBar property, 268 
Content property, 268-269 
height, 269 

IsOpen property, 705-706 
IsSticky property, 270 
Opened and Closed events, 271, 292 
TopAppBar property, 268 
in visual tree, 270 
AppBarPad project, 286-293 
file I/O logic, 292-293 
font size increases and decreases, 288-289 
Wrap Options button, 289 
Wrap Options button handler, 290-291 
App class, 16, 30 

keyboard events, 573 
mouse accelerators, 573 
navigation state, saving and restoring, 569 
OnLaunched method, 557 
page shared data, 575 
view models, instantiating, 612 
application bars, 261, 268-271. See also AppBar class 
buttons, 282-283, 286-293 
buttons, positioning, 287 
button styles, 271-276 
button styles, listing, 273-276 
CheckBox controls on, 283-286 
coloring, 270 
controls on, 269-270 
dismissing, 270-271, 292 
height, 269 

in Internet Explorer, 269 
location, 268 

New (or Add) buttons, 287 
PopupMenu and Popup with, 285-286, 289-290 
program options, positioning, 287 
RadioButton controls on, 283-286 
Segoe Ul Symbol font for, 276-283 
visibility, 268 
Application class, 47 

LoadComponent method, 25 
Resources dictionary, 46 
Resources property, 43 
Resuming events, 246-247 
Suspending events, 246-247 
ApplicationData class, 234, 800 

LocalFolder, RoamingFolder, and TemporaryFolder 
properties, 234 

LocalSettings and RoamingSettings properties, 234 
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ApplicationDataContainer, 234 
container feature, 571 
Values property, 240 

ApplicationForegroundThemeBrush color, 520 
ApplicationForegroundThemeBrush resource 
identifier, 47 

application isolated storage, 249, 308 
application local storage, 234 
font files in, 852-856 
InkManager contents, saving, 1041-1043 
page state, saving, 571-572 
saving unsaved data in, 246 
settings, saving, 733 
TempState directory, 773 
application packages, 824 

ApplicationPageBackgroundThemeBrush color, 520 
ApplicationPageBackgroundThemeBrush resource 
identifier, 16, 47 
applications 

About box, 894-897 
Application derivative, 16 
business logic, 193, 206 
code, 31. See also code 
content, 193 

CoreWindow objects, 184 
data providers, 193 
deploying, 824 
display modes, 549-554 
event processing, 221 
full screen mode, 539 
images, binding to, 12 
language interoperability, 129 
layers of, 193 
layout, 7 

libraries, referencing, 128, 130 

library projects in, 127 

lifecycle issues, 245-249 

markup, 31. See also markup 

multipage, 561-562 

orientation awareness, 539, 554-557 

orientation preferences, 556 

Page derivative, 16 

page-navigation structure, 5 

page structure, 5 

permissions, 894 

presentation layer, 193 

private fonts, 847 

registering for printing, 904 

separation of concerns, 193, 200 

settings, locating, 240 

settings, saving, 288, 308-311, 742, 802 

settings, storing, 234, 240, 308 

Share providers, 903 


Share Targets, 903 
snap mode awareness, 539 
snap modes, 549-554 
suspension, 246-247 
termination, 245-246 
termination, abnormal, 246 
themes, setting, 128 
unsaved data, saving, 245-248 
windows, 5 
application state 

restoring, 568-572 
saving, 568-572 

ApplicationStateSave project, 569-572 
OnLaunched method, 573 
ApplicationView class 

TryUnsnap method, 554 
Value property, 549 

ApplicationViewState enumeration, 550-551 
Filled value, 551, 553 
FullScreenLandscape value, 551 
FullScreenPortrait value, 550 
Snapped value, 552, 553 
application view transitions, 329 
AppSettings class, 308, 733-734, 736 
AutoParsing property, 316 
bindings to, 325 
EditOrientation property, 308 
Orientation property, 311 
properties of program settings, 308-311 
SwapEdit And Display property, 311 
App.xaml.es files, 16 

OnLaunched override, 29 
App.xaml files, 16 

resources, defining, 46 
style definitions, 937 
architectural patterns, 193 
arcs 

algorithms for WriteableBitmap, 722-747 
rendering, 101 
ArcSegment class, 55 

IsLargeArc property, 642 
Point type properties, 361 
ArcSegment structure, 726-727 
ARGB colors, 17 
ARM-based machines, 823 
Arrange method, 485 
ArrangeOverride method, 485, 487, 492 
finalSize method return, 493 
arrow keys as accelerators, 575 
AsAsyncAction method, 243 
Ascender Corporation, 847 
Asin method, 641 


aspect ratio 


aspect ratio 

Grid, responding to changes in, 295 
ignoring, 11, 58 
layout, adjusting, 152-154 
maintaining, 10 
preserving, 396 

properties backed by dependency properties, 296 
Assembly objects, 115-116 
Assets folder, 9,13 
AsStream method, 686 
AsTask method, 243 
asynchronous methods, 221-222 
cancellation in, 231-233, 252, 260 
custom, 250-260 
data, returning to program, 225 
for disk access, 233 
error trapping, 230 
for file I/O, 243-245 
for file picker display, 234 
interface hierarchy, 226 
OpenReadAsync method, 238 
page initialization, calling during, 231 
progress reporting in, 231, 252-254, 260 
RunAsync method, 225 
asynchronous processing, 222 

application lifecycle issues, 245-249 
Async calls, consolidating, 241-243 
await operator, 229-231 
callbacks as lambda expressions, 228 
cancelling operations, 231-233 
errors and, 231 
exception handling, 240-241 
file I/O, 233-235 

MessageDialog examples, 222-227 
.NET support, 242-243 
progress reporting, 231 
async keyword, 230 

in lambda functions, 251, 256 
Async method calls, 222-223 
asyncOp objects, saving as field, 232 
AsyncStatus enumeration, 224, 232 
Async suffix, 221, 222 
Atan2 method, 724 
attached properties, 132-136 
animating, 347-350 
Automation Properties class, 272 
creating, 168 
in custom panels, 484 

Grid.Row and Grid.Column properties, 147, 149 
Grid.RowSpan and Grid.ColumnSpan 
properties, 147, 150 
text-enhancing, 856-857 
Zlndex, 136-137 


AttachedPropertyAnimation project, 347-350 
audio files, 22 

AutolmageSelection project, 546-549 
automation peers, 890 
Automation Properties class, 272 
AutoReverse property, 335, 341 
AutoRotationPreferences property, 556, 957 
availableSize argument, 486, 487 

finite Width and Height properties, 493 
infinite Height property, 496 
await operator, 229-231 

callback method creation, 241 
deferral objects, 230 
flagging methods for, 230 
for long-running jobs, 250-251 
restrictions on, 230 
in Task.Run, 256 
in Task-Yield, 259-260 
in try blocks, 232 

AxisAngleRotation program, 981-986 
azimuth, 986-999 
calculating, 990 

B 

Back buttons, 562-563, 585 
Click handler, 895-896 
disabled, 601-602 
BackButtonStyle, 585 
BackEase class, 357 
background 

colors contrasting with, 47 
of Grid, 7, 16 
light, 16 
of margins, 101 

BackgroundCheckedGlyph, 283 
Background property, 31 
null default value, 82 
of Slider controls, 754 
TemplateBinding on, 508 
Transparent setting, 82 

background threads. See also secondary threads 
animations running in, 330 
Backspace key processing, 887-888 
back stack, 562-563 

saving and restoring, 568-571 
BackStackDepth property, 563, 566 
bar charts, 497-499 
BareBonesSlider project, 522-524 
TemplateBinding, 524 
BasedOn property, 63, 65 
BaselineTiltedShadow project, 829-831 
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bitmaps 


base method calls, 76 
Begin method, 332, 433 
BeginStoryboard class, 360 
BeginTime property, 359 
BerniceBobsHerHair project, 867-869 
BetterBorderedText project, 99-100 
BetterCharacterlnput project, 888-892 
BezierControlPointl property, 1019 
BezierControlPoint2 property, 1019 
Bezier curves 

connecting, 344-345 
Cubic Bezier, 345 
ink as, 1018 

InkStrokeRenderingSegment objects, 1014-1015 
line thickness, 1023 
Polyline, converting from, 1021 
quarter-circle, 344-345 

rendering, 101, 1025-1026, 1034-1035, 1039-1041 
skewing, 406 
Smooth Bezier, 345 
BezierSegment class, 55-56, 361 
BezierSegment properties, 1023 
Bezier splines, 371 
BindableBase class, 201-202 
binding. See data bindings 
Binding class 

ConverterLanguage property, 110 
ConverterParameter property, 110 
Converter property, 109-111 
ElementName property, 67 
Mode property, 199 
Path property, 68 
syntax, 112 

binding converters, 154 

BooleanToVisibilityConverter binding 
converter, 461-462 

Binding markup extension, 66, 88, 112, 474 
on Fill property, 452 
in property-element syntax, 67 
Bing Maps 

map tiles, 1005-1006 
quadkey numbering, 1006-1007 
Bing Maps SOAP service, 1000 
manual use, 1002 
quadkey, obtaining, 1007 
BitmapAlphaMode property, 709 
BitmapCodecInformation objects FriendlyName 
property, 710 
BitmapDecoder class, 704 
CreateAsync method, 708 
creating, 707-708 
file format GUIDs, 704 
GetDecoderlnformationEnumerator, 707 


BitmapEncoder class, 704 
CreateAsync method, 712 
file format GUIDs, 704 

GetEncoderlnformationEnumerator method, 710 
SetPixelData method, 712 
BitmapFrame class 

BitmapAlphaMode property, 709 
BitmapPixelFormat property, 709 
Bitmaplmage class, 27, 683 
creating in code, 28 
BitmapPixelFormat property, 709 
BitmapPrintDocument class, 948-951 
current bitmap, obtaining, 949 
instantiating, 949 
bitmaps, 683-777. See also images 
Alpha setting, 691 
A, R, G, and B value formulas, 691 
in buttons, 450 

camera photos, capturing, 772-777 

in celestial sphere, 992-999 

clipboard support, 898 

color format, 684 

creating, 12 

displaying, 9-13, 687 

displaying from code, 27-29 

file formats, 703-704 

HSL color selection, 747-758 

images on top of, 758 

invalidating, 687 

larger than screen, viewing, 992-999 

line drawing on, 724-747 

loading, 692-694, 703-714, 736-742 

monochromizing, 714-721 

Pictures library, 763-772 

pixel bits, 684-690 

pixel dimensions, 104 

pixel dimensions, calculating, 692 

pixel formats, 709 

pixel sizes, 545-546 

posterizing, 714-721 

premultiplied alphas, 684, 691-696 

printing, 948-951 

program logo bitmaps, 13 

radial gradient brush, 696-703 

resetting, 687-688 

resolution scale, autoselection of, 546-549 
resolution settings, saving, 706, 708 
reverse painting, 758-762 
saving, 646, 703-714, 736-742 
stretching, 58-60 
transparency, 691-696 
updating pixels, 688 
zooming, 998 
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BitmapSource class 


BitmapSource class, 683, 692 

PixelHeight and PixelWidth properties, 684 
BURES value, 1007 
Blank App template, 3, 557 
Block class, 41 
Blocks property, 858 
Bold class, 42 

BooleanToVisibilityConverter binding converter, 461- 
462 

BorderBrush, 505 

predefined identifiers, 128 
Border element, 97-101 
Child property, 98 
for context menus, 268 
in ControlTemplate, 504-505 
Grid in, 146 

HorizontalAlignment and VerticalAlignment 

properties, 99 

Loaded handler on, 267 

Padding property, 100-101 

for printer pages, 911 

RadioButton controls in, 161 

for StackPanel, 266 

TextBlock elements in, 165 

width, 165 

BorderThickness property, 98, 505 
Bosch, Hieronymus, 993 
BottomAppBar property, 268 
BOUNCE constant, 972 
browser keys, 574-575 
Brush class 

RelativeTransform property, 422 
Transform property, 422 
brushes 

animating, 423-427 
class hierarchy of, 31 
defining with styles, 62 
ImageBrush, 690 
radial gradient brush, 696-703 
sharing, 43-47 
SpreadMethod setting, 425 
ToString representation, 451 
transforms on, 422-427 
for visual states, 521 
Brush type, 31 

BubbleLevel program, 966-969 
Buffer class fully qualified name, 694 
bulk access, 235, 237 
business logic, 193 
isolating, 206 
ButtonBase class 

classes deriving from, 159 
Click events, 140, 161 


ClickMode property, 161 
Command Parameter property, 212 
Command property, 212 
Content property, 162 
HorizontalAlignment and VerticalAlignment 
properties, 160 
Margin property, 160 

Button controls, 139, 159-167 
appearance, manipulating, 162 
on application bars, 271-276, 286-293 
BorderBrush property, 505 
BorderThickness property, 505 
Cancel buttons, 238, 318 
Click handlers, 166, 237-238, 258, 566 
Command bindings on, 218-219 
Command property, 212-213 
content of, 141 
Content property, 450-459 
ContentTemplate property, 451-452 
Copy and Paste buttons, 898 
custom, defining, 222 
data content, 450-459 
default appearances and functions, 159-162 
223-224 

dependency properties, defining, 167-177 

Don't Save buttons, 318 

enabling and disabling, 258, 933-934, 1011 

EntranceThemeTransition, 512 

forward and back buttons, 558-559 

images in, 162 

implicit style, 165-166 

JiggleButton, 386-387 

keyboard input focus, 513 

MVVM pattern and, 212-213 

names, displaying, 272 

OnCharButtonClick event handler, 167 

Open buttons, 320-321 

Paste buttons, 898-899 

RenderTransformOrigin property, 387 

RenderTransform property, 387 

Resources property, 387 

Save As buttons, 318-319 

Save buttons, 318-319 

Segoe Ul Symbol font for, 271-272 

static visuals, 504 

style, overriding, 165 

View Model, calling into, 212-213 

visual states, 513-520 

in visual tree, 503 

ButtonVarieties program, 159-162 

By property, 337 

ByteToHexStringConverter converter, 470 
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c 

c# 

anonymous methods support, 228 
async keyword, 230 
in code-behind files, 6 

data type equivalence to Windows API, 780-781 
function declarations, 782 
.NET API access, 779 
platforms for, 823 
platforms, selecting, 822 
property initialization, 24-25 
public fields, 781 
static functions, 782 
structures, defining, 781 
Tapped event, 70 
wrapper DLLs, accessing, 779 
C++ 

native machine code, compiling to, 822 

Platform namespace runtime libraries and 

classes, 779 

platforms for, 823 

public classes, 810 

wrapper DLLs, 779 

CalculatelmageScaleAndOffset method, 758 
CalculateNewTransform method, 445 
Calendar class, 930-931 
calendars, 928-936 
callback methods, 223, 224 

lUICommand object, obtaining, 229 
as lambda expressions, 228 
running in Ul thread, 227 
callbacks, 83-84 

CallerMemberName attribute, 202 
camera application, creating, 774-777 
CameraCaptureUI class, 772 
camera, capturing photos from, 772-777 
Cancel buttons, 238, 318 
CancelCommandIndex property, 224 
CancellationToken type, 252-253, 255 
Cancel method, 223 

of lAsyncInfo interface, 231-232 
CanExecuteCalculate method, 215 
CanExecuteChanged handler, 213 
CanExecuteDeleteCharacter method, 218 
CanExecute method, 213, 215 

Func<object, bool> delegate, 214 
CanGoBack and CanGoForward properties, 557, 558 
as binding sources, 560 
CanRecorderltems property, 599 
Canvas, 132-136 

animating, 347-350 
attached properties, 132-136 


Canvas.Left and Canvas.Top attached properties, 
animating, 347-350, 358-359 
Canvas.Left and Canvas.Top attributes, 133 
Canvas.SetLeft and Canvas.SetTop static 
methods, 135 

children, arrangement of, 97 
children, size of, 137 
clipping, avoiding, 137-138 
DependencyProperty property, 135 
element-positioning properties, 132 
HorizontalAlignment and VerticalAlignment 
properties, 137 
layout in, 137-138 
pagination and, 921 
SetLeft and SetTop methods, 135,136 
TextBlock, positioning, 306 
Zlndex property, 136-137, 435, 436 
capacitance pens, 1014 
CaptureFileAsync method, 772-773 
CapturePhotoToStorageFileAsync method, 775 
CapturePhotoToStreamAsync method, 775 
CapturePointer method, 628 
Carroll, Lewis, 345, 859 
Ceiling method, 921 
celestial sphere, 986 
altitude, 986 
azimuth, 986 
bitmaps in, 992-999 
horizontal coordinate, 987 
nadir, 986 

CenteredTransforms project, 673-674 
center of rotation, 378, 398. See also rotation 
protection radius around, 678 
for single-finger rotation, 678 
specifying, 383-386, 391-396 
for touch interfaces, 673-676 
CenterOfRotationX, CenterOfRotationY, 
CenterOfRotationZ properties, 434 
CenterX and CenterY properties 
handlers for, 385 

of RotateTransform class, 383-384 
of ScaleTransform class, 398 
CharacterFormat property, 877 
CharacterReceived events, 184, 887 
handling, 889-890 
char data type, 277 
charms, 893 

Devices charm, 904-911 
displaying, 286 
hooking into, 896 
program invocation, 928 
Settings charms, 894-897 
Share charm, 898-902 


Char structure 


Char structure, 277 

ConvertFromUtf32, 281 
char values, 887 
CheckBox controls, 161 
styling, 285 

Checked and Unchecked events, 161 
Checked handlers, 180-181, 265, 274 
ChecklfOkToTrashFile method, 320, 900-901 
CheshireCat project, 345-347 
children 

dependency property, setting on, 135-136 
and parents, balancing needs, 97 
size of, calculating, 490 
stacking, 103-104 
Children property, 24, 103 
of Storyboard class, 337 
of TransformGroup class, 391 
ChildrenTransitions property, animating, 376 
CircleAnimation project, 358-359 
circles. See also Ellipse class 
quarter-circle arcs, 344-345 
rendering, 102, 105 
CircularGradient project, 688-690 
Classl.cs files, 127 
classes 

abstract classes, 117 
attached properties, creating, 168 
content properties, 38-41 
dependency properties, defining, 168-177 
nesting, 42 

order of elements in code, 172 
protected constructors, 117 
class hierarchies, 114-118 
Class Library template, 129 
Click handlers, 166, 212, 928 
animations, triggering, 387 
for Back buttons, 895-896 
for buttons, 566 
in context menus, 265 
for file picker Open button, 237-238 
lambda functions in, 228 
null values, 242 
for Start buttons, 258 
clicking, enabling, 599 
ClickMode property, 161 
clipboard 

bitmaps, copying and pasting, 898 
contents, checking, 899 
copies and pastes, 877 
Ctrl+C and Ctrl+V support, 902 
ink, copying to, 1037 
pasting into InkManager, 1029 
sharing data with, 898-902 


Clipboard class, 899 

GetContent method, 899 
SetContent method, 899 
ClockButton project, 456-459 
Clock class, 456-459 
ClockRack program, 786-808 
Add menu item, 803 
clock size, 794 
Delete item, 804-805 
DistributedUniformGrid class, 799-800 
Edit and Delete options, 802-803 
Edit option, 804-805 
Closed event handler, 327 
Close method, 223 
code, 31 

animations, defining in, 338 
application bars, dismissing, 270-271 
attached properties, setting, 133 
Auto or star sizes, specifying, 147 
Binding object, creating, 67-68 
callback methods, 223 
element properties, changing, 69 
font files, referencing, 856 
FontUri property, setting, 852 
gradient brush, 31-33 
Grid, accessing, 28 
images, displaying, 27-29 
items, generating, 467-468 
ItemsSource property, setting, 471-472 
Path element in, 56-57 
PopupMenu objects, constructing, 262 
private fonts, referencing, 850 
queuing, 225 

RichTextBlockOverflow, generating, 867 
styles, defining, 62 
test, setting, 184 
TextBlock, creating, 24-27 
View Model, instantiating, 205 
code-behind files, 6 

elements, accessing, 69 
event handlers in, 71 
Grid, accessing from, 23 
minimizing use of, 194 
of XamICruncher, 313-315 
codecs, 704 

CollectionChanged events, 475, 591 
collection controls, 463-474 
collections, 474 

Dictionary<TKey ( TValue 〉 collections, 474-475 

displaying, 141 

of groups, 611 

items, accessing, 474 

items, adding and removing, 591 
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content 


collections {continued) 

items, displaying, 449, 464, 477-478, 596-597, 600 
items, grouping, 608-611 
ItemsSource property, binding to, 473 
List<T> collections, 474-475 
movement of items, 329 
selecting items, 475-480 
CollectionViewSource class, 611 
ColorAnimation class, 361 
ColorAnimation Using Key Frames class, 369-370 
Colorltems project, 467-469 
ColorltemsSource project, 470-472 
ColorltemsSourceWithBinding project, 473-474 
ColorKeyFrame class, 369 
ColorListl project, 122-124 
ColorList2 project, 124-126 
ColorList3 project, 127-129 
Color property, 157 
animating, 331 
binding on, 453 
public, 755 

setting from outside, 757 
colors 

animating, 92-96, 331 
color format of bitmaps, 684 
gradients between, 32 
highlight colors, 47 
HSL color selection, 747-758 
Hue, 747 
Lightness, 747 
listing, 122-124 
Saturation, 747 
specifying, 16-17 
transparent black, 762 
transparent white, 762 
color schemes, 16 
Colors class, 17, 588 
using directive, 23 

ColorScrollWithDataContext project, 202-206 
ColorScrollWithValueConverter project, 155-157 
ColorScrollWithViewModel project, 196-201 
COLORSCR program, 148 
ColorSettingDialog class, 743-744, 757 
Color structure, 835 
ColorTextBoxes project, 206-208 
ColorTextBoxesWithEvents project, 209-211 
ColorToContrastColorConverter, 494 
ColorWrap project, 130-131 
ColumnDefinition objects, 146 
ColumnDefinitions collection, 146 
columns, 131 
COM API, 779 


ComboBox controls, 464, 805, 807 
processing, 1054-1056 
ComboBoxItem class, 535 
COM (Component Object Model), 779 
commanding, MVVM architecture and, 193 
command interface, 212-213 
Command Parameter property, 212 
Command property, 212-213, 218-219 
commands 

on application bars, 268 
in context menus, 264 
navigating with Tab key, 268 
processing, 897 
sharing, 218 

for View and View Model interactions, 194 
in View Model, 213-219 
CommandsRequested handler, 896 
Common folder 

RichTextColumns class, 867 
StandardStyles.xaml file, 46 
CommonMatrixTransforms project, 417-418 
Compass class, 974-976, 980 

accelerometer data and, 976-986 
CompassReading class, 974 
Completed callback method, 224 
Completed events, 338, 579 
Completed handler, 226, 580 
running, 228 
Completed property, 223 
Complete method, 663 
CompositeTransform class, 379, 419-421 
composite transforms, 418-421 
CompositionTarget.Rendering events, 91-96, 329, 802, 
841-843 
ComPtr, 810 
computers 

geographical location, 671-672, 999-1012 
screen resolution, 539-545 
sensory hardware, 953-1012 
ConditionalClockButton project, 460-463 
conditional execution in XAML, 460-463 
constructor 
defining, 126 

DependencyProperty objects, creating, 168 
initializing components in, 150 
Loaded processing, 86 
public parameterless, 474 
ContactRect property, 633 
Container property, 677 
containers, filling with images, 11-12 
content, 193. See also data 
docking in Grid, 158 
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ContentControl class 


ContentControl class, 141, 472 
AppBar, 261 

ContentPresenter class, 509, 667-669 
Content property, 141, 509 
ContentTemplate property, 451, 467 
ContentPresenter class, 509-510, 667-669 
bindings on, 510 
Content property, 509 
ContentTemplate property, 510 
ContentTransitions property, 512 
HorizontalAlignment and VerticalAlignment 
properties, 511 
Margin property, 510 
positioning within parent, 512 
content properties, 37-41 
definition, 39 

TextBlock content property, 41-43 
Content property, 28, 38, 97, 564 
of AppBar class, 268-269 
of Button class, 162-163, 450-459 
of ContentControl class, 141, 509 
of ContentPresenter class, 509 
of RadioButton controls, 160 
of UserControl, 125 
ContentProperty attribute, 38 
ContentPropertyAttribute class, 38 
ContentTemplate property, 451-452, 467 
of ContentPresenter, 510 
DataTemplate on, 459 
ContentTransitions property 
animating, 375 
bindings on, 512 

ContextMenuOpening events, 862 
context menus, 261-264 
Border for, 268 
commands in, 264 
creating, 631 
dismissing, 267 
displaying, 267, 632 
horizontal lines, 263 
keyboard interface, 264 
location, 263-264, 266 
navigating with Tab key, 268 
positioning, 267 
of TextBox control, 262 
continuation handlers, 594 
Control class, 139-141 

classes deriving from, 139-141 

event interface, 75 

Focus method, 140 

FontFamily property, 845 

Foreground property, 162 

HorizontalContentAlignment property, 140, 511 


IsEnabledChanged event, 140 
IsEnabled property, 140 
IsTabStop, Tablndex, and TabNavigation 
properties, 140 

OnGotFocus and OnLostFocus virtual methods, 140 
On methods, 615, 656 
Padding property, 510 
properties of, 140 
protected virtual methods, 140 
Template property, 139, 502, 503 
VerticalContentAlignment property, 140, 511 
controls 

appearance, defining, 329 

appearance, redefining, 139, 140 

on application bars, 270 

automation peers, 890 

bindings to elements, 506-508 

buttons, 159-167. See also Button controls 

chrome, 502-503 

collection controls, 463-474 

in context menus, 261 

custom. See custom controls 

dependency properties and, 167-177 

disabled visual state, 516 

vs. elements, 14 

event handlers, sharing, 167,177 

hit testing, 649-650 

identifying, 177 

input focus, 140, 144, 184, 516 

interaction with user, 139, 140 

items in collections, accessing, 474 

keyboard input, 184-187 

pointer input, handling, 615 

RadioButton, 177-183. See also RadioButton 

controls 

separate instances of, 937 
Setter objects on, 503 
size, defining, 653 

Slider, 141-145, 154-159. See also Slider controls 

Style definitions, 521 

templates on, 502-512 

TextBox, 184-187 

Thumb, 187-192 

in View, binding to properties, 196 
visual appearance, 14 
visuals, customizing, 449 
ControlTemplate class, 449, 502-512 
of AppBarButtonStyle, 271 
Border in, 504-505 
button visual states, 513-520 
definitions in generic.xaml, 520 
hard coding in, 508 
as a resource, 503 
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ControlTemplate class {continued) 
for Slider controls, 754 
as a Style, 506-507 
TargetType property, 503 
TemplateBinding, 506 
converter class, 155-157 
ConverterLanguage property, 110 
Converter property, 109-110 
Convert method 

parameter and language arguments, 110-111 
TargetType argument, 110 
value argument, 110 
coordinate systems 
device, 981 
Earth's, 981 
hardware, 960-961 
right-hand rule, 960 
translating between, 989-990 
of windowing environment, 33,49 
Copy buttons, 898-899 
Ctrl+C support, 902 
Copy command, 898 
CopySelectedToClipboard property, 1029 
CoreDispatcher class, 225 
callbacks, 228 
RunAsync method, 225 
CoreDispatcher objects, 594, 950 

user-interface thread, interacting with, 954 
CoreVirtualKeyStates enumeration, 575 
CoreWindow class, 184,616 

AcceleratorKeyActivated event, 572-573 
CharacterReceived events, 887 
CornerRadius property, 508 
C Programming Language, The (Kernighan and 
Ritchie), 3 

CreateAsync method, 708, 712 
CreateFileAsync method call, 248 
CreateltemListOption method, 944 
CreatePrintTask method, 907, 948 
CreateTextOption method, 944 
CreationCollisionOption, 248 
•cs extension, 4 

Ctrl+C and Ctrl+V support, 902 
Cubic Bezier, 345 
CubicEase class, 357 
Cumulative property, 663 
CurrentOrientation property, 87, 554 
of DisplayProperties, 955 
Current property, 234 
cursor position, obtaining, 307, 882 
curves, 53. See also Bezier curves 
rendering, 101 

CustomButtonTemplate project, 517-520 


custom classes 

animating, 364-367 
BitmapPrintDocument class, 948-951 
Clock class, 456-459 
Dial class, 678-682 
InkFileManager class, 1038-1039 
Key class, 650-655 
Manipulation Manager class, 675-676 
NamedColor class, 469-470 
PieSlice class, 364-367 
Pointerlnfo class, 622 

RadialGradientBrushSimulator class, 696-702 
SaveStatePage class, 565-568 
SecondPage class, 557-559, 566 
StudentBody class, 590-591 
StudentGroup class, 609 
StudentGroups class, 609-610 
SurfacelmageSourceRenderer class, 831-843 
TimeZoneManager class, 789 
TwelveHourClock class, 460-463 
YellowPadPage class, 1043 
custom controls, 530-535 

application projects, defining in, 535 
arranging code, 172 
creating, 141 

default ControlTemplate, 530 
default Style, 530 

dependency properties in, 167-177 
existing controls, adapting, 502-503 
HsIColorSelector control, 752-754 
keyboard input, 184 
library, 531 
local prefix, 174 

LoggerControl control, 622-624 
ManipulableContentControl control, 763 
ManipulationModeCheckBox control, 657-659 
MonthYearSelect control, 930, 932 
NewToggle control, 530-535 
property-changed handlers, 173 
RudimentaryTextBox, 889-892 
UserControl, deriving from, 125, 175-177 
XYSlider control, 667-672 
CustomGradient project, 685-689 
code-behind file, 685 

CustomizableClassHierarchy project, 923-927 
CustomListBoxItemStyle project, 536-538 
CustomPageRange class, 940-942 
custom panels, 484-497 
Arrange method, 485 
ArrangeOverride method, 485 
attached properties in, 484 
finalSize argument, 492 
layout passes, 485, 489 


1067 


custom panels (continued) 


custom panels {continued) 

Margin property, 490 
Measure method, 485 
MeasureOverride method, 485 
properties handled automatically, 485 
scrolling, 484 
size, calculating, 490-491 

D 

data 

automatically saving, 249 

in buttons, 450-459 

displaying, 194 

notifications of updates, 194 

passing and returning among pages, 575-581 

sharing through clipboard, 898-902 

updating upon input focus change, 208-209 

data bindings, 66-68 

Angle property, setting, 380-381 
between dialogs and applications, 268 
binding converters, sharing, 111-112 
Button calls into View Model, 212-213 
changing values, tracking, 144 
Command property targets, 212 
DataContext property of target, 204-206 
data conversion, customizing, 109-111 
in DataTemplate, 452-454 
dependency property target, 89 
document pages, chaining, 863-864 
double types, 198 
elements to controls, 506-508 
items, accessing with, 597 
ItemsSource property to collections, 473 
MVVM architecture and, 193 
notifications, 194-196 
Path= 205 

RelativeSource bindings, 480, 506 

to Run property, 87-89 

source, 67, 177, 194-195 

source, specifying, 194, 199, 200, 204-206 

source, updating, 199 

target, 67, 108-109, 157, 194 

target, updating, 199 

TemplateBinding bindings, 506 

in templates, 449, 452-454 

two-way, 506 

View and View Model interactions, 194 
in View Model, 194-196 
on Visibility property, 462 
XAML resources, referencing, 198-199 


DataContext property, 204-206 
bindings on, 805 

propagation down visual tree, 204 
data conversions, customizing, 109-111 
data entry validation, 210-211 
DataPackage objects, 899 

SetBitmap method, 899-900 
DataPackageView objects, 899 
Data Passing And Returning project, 575-581 
Data property, 53, 56 
null, 57 

data providers, 193 
DataReader class, 237 

IDisposable interface, 238 
DataRequested handler, 903 
DataTemplate class, 449 
adding, 597-598 
bar charts, 497-499 

on ContentTemplate property, 451-452, 459 
data bindings in, 452-454 
for ItemsControl controls, 463-474 
ItemTemplate property, setting to, 466-467 
for ListBox controls, 479-480 
object rendering, controlling, 458-459 
property changes, responding to, 475 
Resource section, defining in, 454 
sharing, 600-601 
DataTransferManager class, 903 
DataWriter class, 237 

StoreAsync method, 239 
DataWriteStoreOperation objects, 239 
DateTime property, 799 
decoders, 704 

DefaultCommandIndex property, 224 
DefaultStyleKey property, 530 
deferral objects, 230 
DelegateCommand class, 213-219 

RaiseCanExecuteChanged method, 214 
delegates, predefined, 214 
DeleteCharacterCommand property, 215-216 
DeleteSelected method, 1029 
Delta property, 660 
DependencyObject class, 15 

accessing from thread of execution, 225 
Dispatcher property, 225 
SetValue method, 135 
thread safety, 224-225 

DependencyObjectClassHierarchy project, 114-118 
dependency properties, 15, 25-26 
animating, 94 

attached properties, 132-136 

as backing for data binding targets, 89, 194 

binding sources, 194 
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DisplayMemberPath 


dependency properties {continued) Win32 function conversions in, 789 

as binding targets, 67 Dictionary class, 255 

children, setting on, 135-136 Remove method, 567 

for controls, 167-177 Dictionary<TKey, TValue> collections, 474-475 


on Canvas, 135 

default value, 15 

defining, 26, 167-177 

defining as private static fields, 169 

existing types for, 297 

in RadialGradientBrushSimulator, 696-698 


DigitalClock project, 90 
digital stylus, 1014. See also pens 
digitizers, 1014. See also pens 
Direct3D, 380 

directory structure, displaying, 765-766 
DirectWrite, 809-821 


Matrix3D type, 443 

properties, specifying independently of class, 62 
property changes, 96 
target properties of animations, 330 
DependencyProperties namespace, 174 
DependencyPropertiesWithBindings project, 176-177 
DependencyPropertyChangedEventArgs objects 
Property property, 171 
DependencyProperty class, 15 
RegisterAttached method, 168 
Register method, 168 
DepthText project, 390-391 
designllnitsPerEm field, 827 
Desired Deceleration property, 664 
Desired Displacement property, 664 
Devicelnformation objects, 774 
devices. See also printers; tablets 
orientation changes, 9 
Devices charm, 904-911 
program invocation, 928 
Dial class, 678-682 
Dial controls, 678-682 

Minimum and Maximum values, 680-681 
RotateTransform, 681 
dialog boxes 

for file opens and saves, 234-235 
Popup class for, 265-268 
DialogPage class, 575-581 
Completed event, 579-580 
DialSketch project, 679-682 
dictionary 

abandoned entries, 633 
back stack information, 572 


DWRITE_FONT_METRICS ; 827 
font family names, 815 
font metrics, 825-831, 856 
fonts, enumerating, 847 
pages, rendering, 921 
DirectX, 48 

DirectWrite, 809-821 
drawing on bitmaps, 831-843 
HRESULT values, 811 
libraries, 809 
SharpDX library, 808 
DirectXWrapper library, 808-809 

correspondence with DirectWrite interfaces, 809- 
810 

fonts, enumerating, 820-822 
referencing, 820 

SurfacelmageSourceRenderer class, 831-843 
WriteFactory class header file, 810 
DirectXWrapper project, 808-809, 880 
DiscreteObjectKeyFrame class, 371 
Value property, 372 
DiscretePointKeyFrame class, 368, 369 
Dispatcher property, 225, 594 
DispatcherTimer class, 89,232 
interval, 405 

for long-running jobs, 250 
timer interval, 90 

DisplayAndPrinterPrep method, 915-916 
DisplayGrid property, 766 
DisplayHighSchoolStudents project, 594-608 
Back button, 601-602 
GridView, 602 
ItemClick events, 605-606 


Color type values, 634 

instantiating, 565 

of MIME types, 710 

page state information, 564-567 


ListView, 602 

portrait mode, 605-606, 608 
Snapped mode, 604 
StudentPage.xaml file, 606-608 


per-finger information, 622-627 


Visual State Manager markup, 602-603 


Pointer IDs, 618, 619, 621-622, 627 
Pointer IDs, removing, 630 
pointer information, 634, 1024 
removing entries, 567-568 
static pages dictionary, 565, 567 


visual state, setting, 600 
Displaylnformation collection, 791 
Displaylnformation property, 792 
DisplayMatrix3D class, 442-444 
DisplayMemberPath, 477 


1069 


DisplayOrientations enumeration 


DisplayOrientations enumeration, 87, 955 
LandscapeFlipped value, 554 
Landscape value, 554 
members, order of, 556 
None value, 554 
PortraitFlipped value, 554 
Portrait value, 554 

DisplayProperties class, 16, 87, 540, 554-557 
AutoRotationPreferences property, 556, 957 
CurrentOrientation property, 554, 955 
LogicalDpiChanged event, 540 
LogicalDpi setting, 541 
NativeOrientation property, 554, 957 
OrientationChanged events, 554 
SimpleOrientationSensor correspondence, 957 
DisplayText property, 215 
display, themes, 520 
DistributedUniformGrid class, 799-800 
populating, 800-801 
DIUs (device-independent units), 545 
DIIImportAttribute, 781-782 
Document property, 877 
doNotSetSliders field, 757 
Don’t Save buttons, 318 
dot products and cross products, 989 
DoubleAnimation class, 330-331, 340-347 
AutoReverse property, 335, 348 
BeginTime property, 359 
By property, 337 
class hierarchy, 337 
Duration property, 339 
EasingFunction property, 336-337 
EnableDependentAnimation property, 337 
FillBehavior property, 334 
From value, 333-335, 348 
RepeatBehavior attribute, 335, 348 
reusing in animations, 339 
To value, 334-335, 349 
DoubleAnimation objects, 387 
for brush animations, 427 
duration, 433 
From value, 410 
grouping, 396 
To value, 409, 424 

DoubleAnimation Using Key Frames class, 369, 410, 436 
Double.IsPositivelnfinity method, 486 
DoubleKeyFrame class, 369 
DoubleTapped events, 615 
DoubleToStringHexByteConverter class, 278 
double values 

animating, 331, 340-347 
converting to hexadecimal, 155-157 


DPI (dots per inch), 539 
logical DPI, 540 
DragCompleted events, 187 
DragDelta events, 187, 190 
DragEnter events, 70 
DragLeave events, 70 
DragOver events, 70 
DragStarted events, 187 
drawing. See also FingerPaint projects; pens 
redraw methods for, 303 
DrawingAttributes property, 1019 
drawings. See also FingerPaint projects; pens 
saving, 646 
DrawLine method, 835 
Drop events, 70 
Duration property 
overriding, 351 
setting, 339 
DWORD_PTR, 781 
DWORD values, 780 
DWriteCreateFactory function, 810 
dynamic layout system, 97. See also panels 
DYNAMIC_TIME_ZONE_INFORMATION structures 
TimeZoneKeyName field, 792 



Earth 

coordinate system, 981 

coordinate system, transforming to rectangular 
coordinates, 990-999 
longitude and latitude, 986 
EarthlyDelights program, 987-999 
Matrix3D inversion, 989-990 
tilt, calculating, 990-992 
zooming operation, 998 
Ease function, 351 
Ease method, 350 
EasingColorKeyFrame, 371 
Easing DoubleKeyFrame, 371 
EasingFunctionBase class, 336-337 
EasingMode property, 337 
EasingFunction property, 336-337 
easing functions 
elapsed time, 351 
SineEase function, 358 
values outside range of 0 and 1, 357-358 
visual representation, 351 
EasingMode function, 387 
EasingMode property, 337, 358 
EasingPointKeyFrame class, 369, 371 
EasyCameraCapture program, 772-774 
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e-book readers, 870-877 
page numbers, 871-873 
e-books,creating, 119-122 
EditBox controls, 805 
EditOrientation enumeration, 322 
EditOrientation property, 308 
EditOrientationRadioButton controls, 322-327 
ElasticEase animation, 387 
EaselnOut mode, 393 
ElasticEase class, 336, 357 
Oscillations property, 337 
Springiness property, 337 
electromagnetic pens, 1014. See also pens 
ElementName property, 67, 194, 204 
elements 

accessing from code-behind, 69 

binding to controls, 506-508 

centering, 107-108 

clipping, avoiding, 137-138 

vs. controls, 14 

fading in and out, 345-347 

flipping horizontally or vertically, 398 

interaction with user, 139 

jiggling, 386-387 

keyboard focus, 630 

layout of, 937 

location, finding, 427-430 

manipulation, enabling, 656 

margins, 100-101 

naming, 126 

natural size, calculating, 490 

offsetting from original position, 388-391 

organizing, 20 

overlapping, 19-20, 136-137 

overlapping, preventing, 20-22 

padding, 101 

vs. panels, 14 

pointer capture, 615, 622-630 
pointer input, 627 
positioning precisely, 132-136 
Position property, 618 
properties, linking, 66 
rendered size, 85 


transforms on, 377. See also transforms 
visual state elements, 513 
in visual tree, accessing, 143 
visual tree of, 14 
width and height values, 98 
Z order, 20 
Eliot, George, 870 

EllipseBlobAnimation project, 340-341 
Ellipse class, 101-103 
animating, 341-342 
Height and Width values, 102, 104 
rendering, 101-102 
Stretch property, 105 
StrokeDashArray property, 343 
StrokeDashCap property, 343 
StrokeDashOffset property, 343-344 
EllipseGeometry class 
animating, 361-363 
positioning element, 970 
EIPasoHighSchool project, 589-608 
student.xml file, 591-592 
El Paso Public Library, 589 

EnableDependentAnimation property, 331-332, 337 
leaving out, 348 
EnclosureLocation property, 774 
encoders, 704 
EndPoint property, 33 
EntranceThemeTransition, 512 

EnumDynamicTimeZonelnformation function, 787, 791 
EnumerateFonts project, 820-822 
enumeration types, 24 
EPUB, 856 

erasing, 1014, 1023-1029 
enabling, 1024 
ErrorCode property, 232 
ErrorText property, 926-927 
error trapping in asynchronous methods, 230 
Esc key 

button triggered by, 224 
processing, 629-630 
Euler angles, 976-981 
Euler, Leonhard, 976 
event handlers 


rendering of, 83 
resources, sharing, 43-47 
reusing, 937 
shearing, 406 

size, increasing and decreasing, 396 
spinning in space, 431-434 
stacking, 19-20 


attaching to events, 72 
in code-behind file, 71 
naming, 71 
private keyword, 71 

properties and methods of event, 70, 72 
sharing, 72-73, 142, 167, 177 
source of event, 70, 72 


stretching to parent size, 98 
styles, 60-65 


strings, differentiating, 178 
for Thumb controls, 300-301 
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event handling, 69-96 
AddHandler method, 79 
for animations, 89-96 
Handled property, 78 
Handled property override, 78-79 
for orientation changes, 87 
routed event handling, 72-78 
routed input handling, 74-75 
for size changes, 83-87 
structuring, 633 
timer events, 89-96 
events, 69, 83-84 

application suspension, 246-247 
hiding consumer from provider with, 580 
processing, 221 
routing up visual tree, 78 
source of, 74-75 
Tapped event, 69-72 
virtual methods for, 75 
EventTrigger class, 360 
exception handling 

in file pickers, 240-241 
operation cancellation, 253 
in XamICruncher, 316-318 
exceptions, while saving files, 319 
ExecuteAddCharacter method, 218 
ExecuteCalculate method, 215 
Execute method, 213, 215 

Action<object> delegate, 214 
add argument, 212 
ExpandingText project, 91-92 
ExpansionBehavior property, 664 
Expansion property, 660 
ExponentialEase function, 351 



F5 key, 8 

FastNotFluid project, 371-372 
Figures property, 53 
Filelnformation class, 235 
file I/O, 233-235 

file pickers and, 235-240 
streamlining, 243-245 
in XamICruncher, 318-321 
FilelO class, 243-245 

ReadLinesAsync method, 243 
ReadTextAsync method, 243 
WriteTextAsync method, 319 
FilelO methods, 292-293 
FileOpenPicker class, 234-240 
invoking, 237 


objects, creating, 706-707 
file pickers, 235-240 

async calls, consolidating, 241-243 
Cancel button, 238 
exception handling, 240-241 
MIME type, indicating, 886 
Open buttons, 237-238 
permissions for file access, 704 
Snapped state, 736 
files 

automatically saving, 249 
canceling opening, 318 
canceling save option, 318 
loading, 238 

reading, 244-245, 254-260 
saving, 239, 318 
storing, 308 

uploading and downloading, 244 
FileSavePicker class, 234-240 
objects, creating, 710 
fileStream objects, 692-693 
reading, 694 

FileTypeFilter collection, 237 
FillBehavior property 
HoldEnd setting, 334 
Stop setting, 334 
Fill property, 101 

animating, 371-372 
Binding markup extension on, 452 
of Glyphs, 851 
FindAIIAsync method, 774 
FingerPaint projects, 619-646 
About box, 894-897 
AppSettings class, 733-734 
blank canvas, 735 

Color and Thickness buttons, 743-744 

ColorSettingDialog, 757 

CreateTaperedLineGeometry, 642-644 

Dictionary definition, 619 

editing features, 630-633 

Esc-key processing, 629-630 

existing files, drawing on, 735 

Grid name, 619 

HSL structure, 747-749 

input outside page, 622 

ItemTemplate, 746 

line taper, smoothing, 637-646 

MainPage.File.es file, 736-742 

MainPage.Pointer.es file, 731-732 

MainPage.xaml.es file, 742-744 

MainPage.xaml file, 735 

multiple-finger polylines, 621 

OnMenuDelete method, 633 
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ForeverColorAnimation project 


FingerPaint projects {continued) 

OnPointerReleased and OnPointerCaptureLost 
overrides, 644-646 
Pictures library access, 736 
pointer capturing, 634-635 
Pointerlnfo structure, 634-635 
PointerPressed event handler, 631 
popup menu logic, 631 
pressure sensitivity, 633-637 
printing, 948-951 
RenderOnBitmap method, 729-731 
RightTapped event handler, 631 
saving, 722-747 
Share charm support, 903 
snap mode, 621-622 
ThicknessSettingDialog, 743-746 
Vector2 structure, 638-646 
Visual State Manager markup, 736 
fingers 

consolidating input with Manipulation events, 616, 
655 

contact area bounding box, 633 
multiple, drawing with, 839-843 
multiple polylines from, 621 
multiple, tracking, 669, 749-752 
single-finger rotation, 676-682 
tracking movement, 615, 618, 652-653 
FitToCurve property, 1017-1018 
Fitzgerald, F. Scott, 867 
FixedPage class, 853 
FlickAndBounce project, 665-667 
flip panels, 434-437 
FlipViewColors project, 500-502 
FlipView controls, 464, 500-502 
for calendar pages, 928,930 
Height and Width properties, 501 
for pages, 587, 870-877, 1038, 1043, 1048-1049 
SelectionChanged handler, 876 
SizeChanged handler, 873-876 
FlipViewItem class, 535 
Focus method, 140, 630 
Folderlnformation class, 235 
FolderPicker class, 234-235 
font families, 845-846 
font files in, 846 
name, 849 


font-related properties, 41, 845 
setting in code, 26-27 
setting inXAML, 7-8 
FontRenderingEmSize property, 851 
fonts 

ascent line, 828 
baseline, 828 

boldface and simulated boldface, 849 

caps height line, 828 

defined, 845 

descenders area, 828 

design height, 15 

enumerating, 820-822, 847 

fixed-pitch, 315 

in local storage, 852-856 

permission to distribute, 847 

pixel height values, 827 

pixels and points, equivalence, 15 

points, 15 

private fonts, 847-850 
referencing in local storage, 855-856 
size, 845 

size at printing, 910 
style simulations, 851 
terminology, 845 

text-enhancing attached properties, 856-858 
typographical enhancements, 856-858 
URIsof, 848-849, 851 
Windows font files, 846 
Fonts directory, 855-856 
FontSize property, 15 
animating, 330-333 
as dependency property, 15 
inheritance of, 21 
FontSizeProperty property, 15 
FontStretch enumeration, 814 
FontStyle enumeration, 814 
FontStyle property, 849, 883 
defining, 26 
using directive, 23 
FontUri property, 851 
setting in code, 852 
FontWeight property, 849 
FontWeights class, 814 
FontWeight structure, 814 
foreach blocks,user interface interaction in, 259 


obtaining, 813-821 
FontFamily class, 845 
FontFamily property, 24, 845, 847-848 
ms-appx prefix, 848 
font metrics, 824-831 

text, positioning precisely, 856 


Foreground property, 24, 31, 189 
color names, 16-17 
of Control class, 162 
default value, 16 
setting in code, 26-27 
setting in XAML, 7-8 
ForeverColorAnimation project, 360-361 
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FormatEffect enumeration, 883 
FormatRtf flag, 886 
FormattedStringConverter class, 154 
FormatText method, 166 
formatting 

converting from decimal to hexadecimal, 155 
paragraph, 858-861, 872-875 
text, 19, 882-883 
Forward buttons, 562-563 
fractionRead values, 876 
Frame class, 29, 557 

back stack, maintaining, 563 

CanGoBack and CanGoForward properties, 557, 

558, 560 

Content property, 557 
GoBack and GoForward methods, 557 
stack of visited pages, 557 
Frame property, 557 

FrameworkElement Automation Peer class, 184 
FrameworkElement Automation Peer constructor, 890 
overriding, 890 
FrameworkElement class, 14 

ActualWidth and ActualHeight properties, 85-86 
classes deriving from, 139 
IsHitTestVisible property, 615 
layout properties, 139 
Loaded events, 86 
Name attribute, 23 
Resources property, 43 
Tag property, 167 
Visibility property, 615 
Width and Height properties, 86 
FrameworkTemplate class, classes deriving from, 449 
French, A. P., 970 
FriendlyName property, 710 
FromArgb method, 24 
FullName property, 595 
Func delegates, 214 

Func<BitmapSource> parameter, 949 
Func<object, bool> delegate, 214 
future objects, 223 

G 

Garden of Earthly Delights, The, 993 
GeneralTransform class 

TransformBounds method, 427 
TransformPoint method, 427 
generated files, 25 
generic.xaml file, 520-521 
ListBoxItem style, 536 
in Themes folder, 530 


Geolocator class, 671-672, 999-1012 
starting sensor, 1005 
Geometry class, 53, 421-422 
Transform property, 421 
geometry, defining, 56 
geometry transforms, 421-422 
GestureRecognizer, 616 
get accessor, 170 
GetAIIX method, 725-727 
GetBitmapStream method, 900, 903 
GetContent method, 899 
GetCurrentOrientation method, 954 
GetCurrentPoint method, 618,1016 
GetCurrentReading method, 958 
GetDecoderlnformationEnumerator method, 707 
GetDefault method 

of Accelerometer class, 958 
of SimpleOrientationSensor, 954 
GetEncoderlnformationEnumerator method, 710 
GetFamilyNames method, 815 
GetFileAsync method, 248 
GetFilesAsync method, 767 
GetFirstMatchingFont method, 814 
GetForCurrentView method, 904 
GetGeopositionAsync call, 672 
GetlmageryMetadataAsync method, 1002 
GetlntermediatePoints method, 618, 1016 
GetKeyState method, 575 
GetLongitudeAndLatitude method, 1007 
GetMapUriAsync method, 1002 
GetMetrics method, 819 
GetNativeSystemlnfo method, 781-782 
GetNavigationState method, 568-569 
GetPageDescription method, 911 
GetPatternCore override, 890 
GetPixelDataAsync method, 709 
GetPosition From Index method, 307 
GetPreviewPage handler, 910, 920 
GetRenderingSegments method, 1019 
GetResults method, 224 

on Completed operations, 232 
GetSystemFontCollection method, 810-812 
GetTemplateChild method, 521 
GetThumbnailAsync method, 767 
GetTimeZonelnformationForYear function, 788 
GettingCharacterlnput project, 887-888 
GetTypelnfo method, 114 
GetWordFrequenciesAsync method, 255-260 
return value, 255 
GIF files. See also images 
frames, extracting, 708 
GlobalOffset properties, 434 
animating, 436 
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Glyphs element, 850-852 
Fill property, 851 

FontRenderingEmSize property, 851 
FontUri property, 851 
Indices property, 852 
OriginX and OriginY properties, 851-852 
parent, 851 
for text layout, 921 
UnicodeString property, 851 
GoBack and GoForward methods, 557, 564, 579 
GotFocus events, 70 
GoToState method, 513, 516, 606 
GPS, 953 

GradientBrushCode program, 32-33 

constructor of the code-behind file, 32-33 
GradientBrushMarkup project, 39-41 
GradientBrushPointAnimation project, 370-371 
GradientButton class property definitions, 170 
GradientOrigin property, 698 
gradients, 32 
animating, 702 
calculation of, 33 
CircularGradient project, 688-690 
CustomGradient project, 685-688 
GradientOrigin property, 698 
interpolation factor, 698 
offset, 33 

OuterColor property, 698 
solid color to transparency, 695-696 
transforms on, 424-427 
GradientStop class, 33, 37 
animating, 361 
Offset property, 94-95 
GradientStopCollection type, 36 
GradientStops property, 33, 36 
graphics 

antialiasing, 758 
negative coordinates, 400-401 
scan lines, 723-724 
graphics composition system 
negative coordinates, 401 
retained mode, 83 
transforms, rendering in, 382 
graphics transforms, 377. See also transforms 
three-dimensional, 430-438 
two-dimensional, 414, 437 
gravity 

effect on rolling ball, 970 
measuring, 958 
GRAVITY constant, 970 
Grid App projects, 539, 581-582, 867 
item templates, 601 
GridLength type, 147 


Grid panel, 7 

accessing from code, 28 

accessing from code-behind file, 23 

animations in, 340 

arrays, defining, 278-280 

aspect ratio changes, responding to, 295 

asterisk (or star) values, 146, 158 

Auto value, 147 

background, 289 

Background property, 31, 82 

in Border, 146 

buttons in, 163-167 

centering, 163 

children, 146,149 

children, arrangement of, 97 

Children property, 24, 37 

contents size, adjusting to fit, 794 

docking content, 158 

Grid.Row and Grid-Column properties, 147,149, 153 

Grid.RowSpan and Grid.ColumnSpan 

properties, 147, 150 

interaction with user, 146-151 

MaxWidth setting for printing, 940 

naming, 23 

nesting, 147, 152 

orientation changes, 9 

Path elements in, 59-60 

RowDefinition and ColumnDefinition objects, 146 

RowDefinitions and ColumnDefinitions 

collections, 146, 152 

rows and columns, 7 

rows and columns, defining, 149, 158 

rows and columns, sizing, 146,147 

rows and columns, specifying, 146 

single-cell, 7 

SizeChanged handler, 190-192, 303 
spinning, 837-843 
styles, defining, 148 
TextBlock children, 19 
Transparent Background property, 82 
VerticalAlignment setting for printing, 940 
in Viewbox, 401-402 
visual objects, places for, 9 
GridView controls, 582-588, 596-608 
grouping items, 608-612 
ItemsSource property, 612 
ObservableCollection type, 608-611 
with view models, 539 
GridViewItem class, 535 
GroupBySex project, 609-611 
GroupedItemsPage.xaml file, 583 
grouping items, 608-612 
GroupName property, 161 


1075 


Handled property 


H 

Handled property, 78, 618 
overriding, 78-79 

HarderCameraCapture project, 774-777 
hardware coordinate systems, 960-961 
HasOverflowContent property, 862, 869 
HasThreadAccess property, 225 
Hawthorne, Nathaniel, 863 
Header property, 325 
HeadingMagneticNorth property, 974-976 
HeadingTrueNorth property, 974-976 
heap allocations, 94 
Height property, 86 
HelloAudio project, 22 
HelloCode project, 23-27 

constructor of MainPage class, 24 
HellolmageCode project, 27-28 
Hellolmage project, 9-13 
image source, 9 

HelloLocallmageCode project, 28-29 
HelloLocallmage project, 12-13 
HelloPrinter project, 905-911 
Hello project, 3-9 

App.xaml and App.xaml.es files, 16 
MainPage.xaml.es file, 4-5 
MainPage.xaml file, 6, 14 
TextBlock class, 7-8 

HelloVectorGraphicsPath project, 56-58 
HelloVectorGraphics project, 54-55 
HelloVideo program, 22 
Heuer, Tim, 823, 953 
hexadecimal 

displaying values in, 148-151 
double values, converting to, 155-157 
Highlight color, 47 
hit testing, 650 

elements, location and orientation, 427 
positioning of elements and, 383 
HoldEnd enumeration, 334 
Holding events, 69, 615, 632-633 
homogenous coordinates, 414 
HorizontalAlignment property, 8, 11, 97-101 
of Border element, 99 
of Canvas, 137 
Center setting, 108 
cropping shapes, 103 
default Stretch value, 98 
default value, 81 
of Ellipse, 102 

HorizontalContentAlignment property, 140, 511 
horizontal coordinate, 987-999 
HorizontalCoordinate values, 997 


HorizontalListBox project, 482-484 
HorizontalScrollBarVisibility property, 113 
HowToAsyncl project, 222, 226-227 
HowToAsync2 project, 228 
HowToAsync3 program, 229-231 
ShowAsync method call, 232 
HowToCancelAsync program, 232-233 
HRESULT values, 811 
HsIColorSelector control, 752-754 
HSL (Hue, Saturation, Lightness) color selection, 747- 
758 

HSL structure, 747-749 
HttpCIient class, 244 
Hungarian notation, 780 
HyperlinkButton controls, 161, 895 


lAsyncAction interface, 225 
AsTask method, 243 
Completed handler, 226 
lAsyncInfo interface, 225 

Cancel method, 223, 231-232 
Close method, 223 
ErrorCode property, 223, 232 
Id property, 223 
interface hierarchy, 226 
Status property, 223, 231 
lAsyncOperation interface, 223, 232 
objects, obtaining, 229 
Status property, 224 
lAsyncOperation<T> interface, 223 
I Buffer objects, 244,686 
ICommand interface, 212 
command validity, 212 

ID2DlBitmapRenderTarget interface, 835-836 
idCustomRangeEdit controls, 945-946 
IDelegateCommand interface, 214 
Identity property, 416 
IDictionary<TKey, TValue> interface, 475 
IDisposable interface, 238 
IDWriteFactory interface, 810 
lEnumerable interface, 464, 474 
IEnumerable<T> interface, 474 
IFormattable interface, 110 
IGeometrySegment interface, 724-725 
Ignorable attribute, 7 
IgnorePressure property, 1017-1018 
llterable<T> interface, 474 
IL (Intermediate Language), 822 
IList interface, 464 
IList<T> interface, 475 
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InkManager class 


ImageableRect property, 911 
ImageBrush class, 31, 52 
gradients in, 690 
ImageSource property, 52 
Stretch property, 52 
Transform property, 53 
ImageBrushedSpiral project, 52-53 
Image element, 10 
class derivation, 14 
defining, 705-706 
instantiating in XAML, 28 
in StackPanel panels, 119-122 
Stretch property, 10-11, 58, 104, 994 
Width and Height settings, 547 
ImageFilelO program, 704-714 
file I/O, 717-719 
Open button, 706-709 
rotating images at save, 712-714 
Save As button, 710-712 
UpdateBitmap method, 720-721 
ImageRotate program, 392-393 
Imagery Service, 1002 
images. See also bitmaps 
applications, binding to, 12 
in buttons, 162 

capturing to memory stream, 775-776 

codecs, 704 

decoders, 704 

displaying, 9-13 

displaying from code, 27-29 

displaying in pixel dimensions, 11 

encoders, 704 

formats, 12 

larger than screen, viewing, 992-999 
layout on page, 11 
loading, 703-714 
raster lines, 723 


implicit styles, 64-65, 459, 530. See also styles 
inhibiting, 68 
implicit typing, 25 
Inclinometer class, 976-980 
instantiating, 978, 983 
starting sensor, 1005 
Indeterminate events, 161 
Indices property, 852 
inertia, 187, 661, 663-667 
acceleration, 664 
deceleration, 664-665 
stopping, 663 
velocity, 663 

InertiaTranslationBehavior class, 664 
inheritance of properties, 21, 63-64 
InitializeComponent method, 5 
code, placing after, 25 
ink, 1013 

continuous strokes, 1018 
copying, 1037 
loading, 1041-1043, 1050 
maintaining, 1014-1017 
saving, 1049 

InkAndErase project, 1024-1029 
Bezier rendering code, 1025-1026 
OnPointerMoved override, 1027-1028 
OnPointerPressed override, 1026-1027 
OnPointerReleased call, 1028 
PointerCaptureLost handler, 1028-1029 
InkDrawingAttributes class, 1014,1017-1024 
default values, 1017 
properties, 1017 

InkEraseSelect project, 1030-1038 
application bar buttons, 1036-1037 
Brush definition, 1030-1031 
Copy logic, 1037 
Grid elements, 1030 


rotating, 392-393 
rotating on save, 712-714 


ink, pasting, 1037-1038 
OnPointerMoved override, 1032 


saving, 703-714, 773 
scaling, 993 
scan lines, 723-724 
size and page size, 10 
Source property, 13, 27, 28 
storing with projects, 12 
stretching, 10-11, 442-447 
Images directory, 12 
ImageSource class, 27 
class hierarchy, 683 
ImageSource property, 52, 831 


OnPointerPressed method, 1031-1032 
OnPointerReleased override, 1033-1034 
InkFileManager class, 1038-1039 
hard-coded default values, 1055 
LoadAsync and SaveAsync methods, 1041-1043 
RenderTarget property, 1040 
InkFileManager property, 1044-1047 
InkManager class, 1014-1017 

CopySelectedToClipboard property, 1029 
default properties, setting, 1018 
DeleteSelected method, 1029 


ImageType Thumbnail property, 769 
IMap<K, V> interface, 475 
ImplicitStyle project, 64-65 


erasing mode, setting, 1026-1027 
ink, copying to clipboard, 1037 
I nkDrawing Attributes objects, 1014 
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InkManager class (continued) 


InkManager class {continued) 

InkStroke objects, 1014, 1018-1019 
methods, 1018 
Mode property, 1024 
MoveSelected property, 1029 
multiple pointers, tracking, 1016 
overhead, 1017 

pen input, collecting, 1015, 1016 
pen thickness and color, saving, 1041 
ProcessPointerDown property, 1016 
ProcessPointerUpdate property, 1016 
ProcessPointerUp property, 1016 
saving contents, 1041-1043 
selection mode, 1029-1038 
SelectWithLine method, 1029 
SelectWithPolyLine method, 1029 
InkManipulationMode enumeration, 1024 
InkStroke objects, 1014, 1018 
Selected property, 1029 

InkStrokeRenderingSegment objects, 1014-1015,1019 
Inline class, 41 
InlineCollection type, 41 
Inlines property, 41, 859 
InlineUIContainer class, 43 
RichTextBlock and, 861 
In Memory Random AccessStream class, 694 
INotifyCollectionChanged interface, 475 
INotifyPropertyChanged interface, 196, 308, 456, 475, 
589-591 

definition, 195 

implementing, 196-198, 202-204 
input devices, 615. See also keyboard input; mouse; 
pens 

input focus, 140, 184 
changing, 144 
data updates and, 208-209 
InputScope property, 185 
Inputstring property, 215 
instances, accessing, 171 
integerLatitude, 1007-1008 
integerLongitude, 1007 
IntelliSense, 8, 27 

enumeration member options, 183 
event handler name suggestions, 70 
events suggestions, 70 
properties suggestions, 70 
interfaces, 474-475 

InternationalHelloWorld program, 20-22 
Internet Explorer application bars, 269 
InvalidateArrange method, 489 
InvalidateMeasure method, 489 
InvalidatePreview method, 927 
Inverse property, 427 


lObservableVector interface, 464 
lOrderedEnumerable type, 255 
IPrintDocumentSource interface, 906 
IProgress<T> type, 253 
IProgress type, 255 

I Random AccessStream objects, 238, 683 
passing to SetSource method, 694 
IsBarrel Button Pressed property, 1014 
IsChecked property, 161 
IsEnabledChanged events, 140 
IsEnabled property, 140 
IsEraser property, 1014 
IsHitTestVisible property, 615 
IsHoldingEnabled property, 632-633 
Isldentity property, 416 
IsImageModified property, 735 
IsInContact property, 618, 627, 650, 1016-1017 
Islnertial property, 665 
IsInRange property, 618, 627 
Islnverted property, 1014 
IsLargeArc property, 642 
IsLightDismissEnabled property, 267, 897 
IsModified property, 307, 308 
isolated storage, 234 
IsPressed property, 650-652 

property-changed handler, 650-652 
IsReadOnly property, 185 
IsSticky property, 270 
IsTextSelectionEnabled, 862 
IsThreeState property, 161 
ISurfacelmageSourceNative interface, 809 
ItemClick events, 599, 602, 605-606 
ItemCollection class, 464 
Add method, 468 
ItemContainerStyle property, 536 
Style on, 536 

ItemContainerTransitions property, animating, 376 
items 

displaying, 600 
grouping, 582, 608-612 
ItemsControl class, 141, 464 
class hierarchy, 463 
ItemContainerStyle property, 536 
ItemsPanel property, 481 
ItemsSource property, 472-473 
in ScrollViewer, 465-466 
templates for, 535-538 
items controls, 464 
bar charts, 497-499 
changes to collection, recognizing, 475 
items, adding, 468-469 
items, displaying, 466-467 
objects, adding, 464 
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LinearGradientBrush class 


items controls {continued) 
panels, specifying, 481 
Selectorltem derivatives and, 535 
String items in, 465 
tap or click interfaces, 476 
ItemsPanel property, 481 

ItemsPanelTemplate class, 449, 481-484, 500-502 
ItemsPresenter element, 535 
ItemsSource property 

binding to collections, 473 
setting, 471 

setting in code, 472-473 
ItemTemplate property, 479 

DataTemplate, setting to, 466-467 
ITextCharacterFormat interface, 877, 883 
ITextDocument interface, 877 
Selection property, 877 
ITextParagraphFormat interface, 877 
Alignment property, 884 
ITextProvider interface, 184, 890 
ITextRange interface, 877 
lUICommand interface, 222-223 
lUICommand objects, 222 

obtaining with await operator, 229 
IValueConverter interface, 110, 155 
IValueProvider interface, 184, 890 
IVector<T> interface, 475 



JiggleButton class, 386-387 
JiggleButtonDemo program, 386-387 
Jobs, Steve, 1013 

K 

Kernighan, Brian, 3 
keyboard accelerators, 572-575 
keyboard focus, 140 
keyboard input, 184-187, 630, 887-892 
button appearance and, 513 
touch keyboard, 184 
keyboard interface 

of context menus, 264 
SmallChange property, 145 
Key class, 650-655 
Key events, 69 

key frame animations, 367-371 
Discrete item, 368 
KeyModifiers property, 618 
KeypadWithViewModel project, 214-219 
KeyTime property, 369 


Key Up and KeyDown events, 184, 887 

Key Up events, 887 

key values collections, 474 



lambda functions 

for Action arguments, 250 
async declarations, 251, 256 
for callback methods, 228, 254 
nesting, 228 

in printing logic, 912, 922 
LanguageFontGroup class, 315 
language interoperability, 129 
laptop coordinate system, 961 
LargeChange property, 145 
LastKeyVisible property, 654 
layout 

aspect ratio, adjusting to, 152-154 
change events, 86 
changes, and animation, 331 
Grid for, 146 
invalidating, 489 
margins in panels, 490 
orientation changes, adjusting to, 152-154 
Panel child classes, 7 
process of, 937 
templates aware of, 539 
LayoutAwarePage class, 581 
LayoutKind enumeration, 781 
layout properties, 139 
layout system 

in Canvas, 137-138 
child-driven, 97, 98 
dynamic nature, 97 
parent-driven, 97, 98 
LayoutTransform property, 382-383 
LayoutUpdated events, 86 
Left and Right arrow keys as accelerators, 575 
libraries, 127-129 
Classl.cs files, 127 
Class Library template, 129 
implicit styles in, 530 
name, 127 
rebuilding, 130 
referencing, 128,130, 820 
sharing, 127, 130-131 
user controls, adding, 127 
LinearGradientBrush class, 31-32 
animating, 370-371 
element size and, 52 
EndPoint property, 33 
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LinearGradientBrush class (continued) 


LinearGradientBrush class {continued) 

GradientStops property, 33, 36, 39 
sharing, 44-47 
StartPoint property, 33 
inXAML, 36 

LinearPointKeyFrame class, 368, 369 
LineBreak element, 43 
LineCapsAndJoins project, 178-181 
LineCapsAndJoinsWithCustomClass project, 182-183 
Line element, 101, 305 
antialiasing, 758 
erasing, 1024 

stroke thickness based on pressure, 636 
visible discontinuities, 637 
Y1 and Y2 properties, 826-827 
LineHeight property, 858 
lines 

algorithms for WriteableBitmap, 722-747 

bitmaps, drawing on, 724-747 

dashed lines, 345 

dotted lines, 513-514 

drawing on SurfacelmageSource, 831-843 

rendered, 722-723 

rendering, 101 

slope-intercept equation, 723 
spiraled lines, 647 

StrokeStartLineCap, StrokeEndLineCap, and 
Stroke Li neJoin properties, 177 
stroke thickness, 633-637 
tapers, smoothing, 637-646 
LineSegment class 

closing figures with, 642 
Point type properties, 361 
LineSegment structure, 725 
LineStackingStrategy property, 858 
ListBox controls, 464 
background, 480 
horizontal, 482-483 
ItemsPanel property, 481 
ItemTemplate property, 479 
multiple selection, 480 
ScrollViewer in, 477-478, 483-484 
UniformGrid in, 495-497 
virtualization of, 481 
width, 477 
ListBoxItem class, 535 
ListBoxItem style, 536 

ListBoxWithItemTemplate project, 479-480, 482-483 
debugging code, 481 
ListBoxWith UniformGrid project, 495-497 
List controls, event IDs in, 652 
lists, displaying items in, 791 
List<T> collections, 474-475 


ListViewBase class, 582 
selection support, 599 
ListView controls, 582-588, 600-608 
grouping items, 608-612 
ObservableCollection type, 608-611 
with view models, 539 
ListViewItem class, 535 
LoadAsync method, 238 
LoadBitmapAsync method overloads, 770-772 
Loaded events, 86 

animations, triggering in, 339, 341, 359 
of Main Page, 247-248 
saving unsaved data during, 248 
Loaded handler, 315 

anonymous method, defining as, 231 
asynchronous methods, calling in, 231 
button creation in, 716 
controls, initializing, 180 
properties, setting, 181 
rotate transforms in, 384 
Storyboard, starting, 349 
translation tags, setting, 394-395 
LoadFileAsync method, 241-242 
LoadFileFromOpenPicker method, 320 
LoadFromStream method, 882, 886 
Load method, 293 
LoadState method, 581 
local namespace declaration, 327 
LocalOffset properties, 434 
local prefix, 7, 174, 198 
local settings, precedence of, 63 
local storage 

application local storage, 234. See also application 

local storage 

font files in, 852-856 

locating, 240 

saving unsaved data in, 245-248 
local time, 787-788 
obtaining, 802 
UTC time, converting, 792 
Location capabilities, 672 
Location property, bindings on, 805 
LoggerControl control, 622-626 
logical DPI, 540 

LogicalDpiChanged handler, 540-541 
Log method, 622-625 

LookAtAppBarButtonStyles program, 273-276 
LookAtFontMetrics program, 824-831 
LostFocus events, 70 
LPVOID, 781 
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Matrix property 


M 

MadTeaParty project, 859-861 
Main method, 25, 30 
MainPage class, 4, 5 

Content property, 28, 557 
data-sharing code, 898-899 
InitializeComponent method, 5 
navigating to, 559-560 
partial keyword, 5 
single instances of, 557, 561 
MainPage.g.cs and MainPage.g.i.cs files, 25 
Connect method, 72 
MainPage.xaml.es files, 4-5 
namespace definitions, 5 
using directives, 5 
MainPage.xaml files, 4, 6 
ManipulableContentControl control, 763 
ManipulationCompleted events, 656, 663 
ManipulationDelta events, 655, 656 
handling, 661, 669 
overriding, 660 

ManipulationDelta properties, 660 
ManipulationDeltaRoutedEventArgs argument, 662- 
663 

Cumulative property, 663 
ManipulationDelta structure, 660 
edge-of-screen detection, 665 
Expansion property, 660 
Scale property, 660 
Translation property, 660 
Manipulation events, 69, 187, 615, 655-663 
centers of scaling and rotation, 661, 673 
Container property, 677 
cumulative manipulation, 663 
horizontal movement, 662 
inertia, 663-667 
inhibiting, 672 
lag time, 616 

multiple fingers, consolidating, 616 
Pivot property, 677 
sequence of, 655-656 
Velocities property, 663 
vertical movement, 662 


setting, 662, 676 

Manipulation Modes enumeration, 656 
TranslateRailsX and TranslateRailsY, 662 
ManipulationStarted events, 655, 656 
handling, 669 

movement required for, 672 
ManipulationStarting events, 655 
Container property, 677 
manipulations, initializing, 676-677 
ManipulationStarting Routed Event Args objects, 678 
ManipulationTracker program, 656-660 
manual animations, 91, 94 
ManualBrushAnimation project, 92-93 
maps. See also Bing Maps 

rotating with orientation of device, 1000-1012 
Margin property, 100-101,121, 858 
of ButtonBase class, 160 
in custom panels, 490 
spacing between paragraphs, 859 
TemplateBinding on, 510 
margins, 100-101 

printable and unprintable areas, 911-914 
for printable pages, 922 
markup, 31 

null, specifying, 68 
property settings in, 34-37 
markup extensions, 44, 67 
Binding, 66-68 
RelativeSource, 68 
StaticResource, 44, 46, 61 
TemplateBinding, 68 
x:Null, 68 

MarshalAs attribute, 791 
Math class 

Atan2 method, 724 
Ceiling method, 921 
Cos static method, 50 
Sin static method, 50 
Matrix3DHelper class, 430 
Matrix3DProjection class, 379, 380 
ProjectionMatrix property, 439 
transform formulas, 440 
Matrix3D structure, 430, 437-447 
fields of, 438 


ManipulationInertiaStarting events, 655-656 
deceleration calculation, 667 
ManipulationlnertiaStartingRoutedEventArgs class, 664 
ManipulationManager class, 675-676, 763-764 
creating objects, 765 

ManipulationModeCheckBox control, 657-659 
ManipulationMode property, 656, 659 
All setting, 662, 665 
non-default values for, 661 


inverting, 986, 989-990 
mapping to video display, 439 
multiplication operator, 447 
numbers, specifying, 439 
Z values, retaining, 439 
matrix multiplication, 413-416 
order of multiplication, 415 
in TransformGroup class, 418 
Matrix property, 427 
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Matrix structure 


Matrix structure, 416 
fields of, 437 
identity matrix, 416 
Identity property, 416 
Isldentity property, 416 
OffsetX and OffsetY properties, 416 
Transform method, 418 
for two-dimensional affine transform, 437 
MatrixTransform class, 379 
matrix transforms, 377. See also transforms 
MatrixTransform structure, 416-417 
maxPageHeight value, 920 
MaxWidth property, 121 
Measure method, 305, 485, 490, 869 
MeasureOverride method, 485-486, 489-490 
availableSize argument, 486 
validity checks, 489 

Width and Height, testing for infinity, 486 
MediaCapture class 

CapturePhotoToStorageFileAsync method, 775 
CapturePhotoToStreamAsync method, 775 
MediaCapturelnitializationSettings objects, 775 
MediaCapture objects, 775 
MediaElement class, 22 
memory allocations for objects, 366 
menus 

context menus, 261-264. See also context menus 
in previous versions of Windows, 261 
Merged Dictionaries collection, 47 
Merged Dictionaries property, 273 
message boxes, 221 
cancelling, 231-233 
MessageDialog class, 221-227 

CancelCommandIndex property, 224 
cancelling, 232-233 
DefaultCommandIndex property, 224 
displaying, 223 
invoking, 226-227 
ShowAsync method, 221 
method calls, await operator in, 230 
methods 

asynchronous, 221-222. See also asynchronous 

methods 

renaming, 71 

Microsoft Expression Blend, 7, 449 
Microsoft PixelSense, 837, 843 
Microsoft Prism framework, 213 
Microsoft Surface, 635, 953, 1013 
AxisAngleRotation on, 985 
compass direction detection, 976 
pointer input, 1015 

remote deployment of applications on, 823 
SensorRotationMatrix, 981 


Microsoft Systems Journal, 83, 148 
Microsoft Word, ink capabilities, 1037 
MinimumReportlnterval property, 959 
MinWidth and MaxWidth properties, 147 
Mobius, August, 414 
Model layer, 193-194 
Mode property, 676, 1024 
OneTime setting, 199 
OneWay setting, 199-200 
TwoWay setting, 199 
monthly calendars, 928-936 
MonthYearSelect control, 930, 932 
mouse 

buttons, navigating with, 572-575 
button states, obtaining, 573 
input, distinguishing, 650 
Manipulation events from, 656 
PointerEntered events, 650 
PointerMoved events, 617 
Position property, 669 
text selection, 862 
mouse wheel, 617 
movement, smoothing, 970 
MoveSelected property, 1029 
ms-appdata prefix, 244, 249 
MVVM (Model-View-ViewModel) pattern, 193-194 
buttons and, 212-213 
calling hierarchy, 194 
command interface, 212 
events, 194 
Model layer, 193 
for small programs, 193, 200 
View, 193 

View Model, 193. See also View Model 

N 

NaiveBorderedText project, 98-99 
Name attribute, 23, 69 
NamedColor class, 469-470, 807 
constructor, 474 
lEnumerable interface, 474 
namespace declarations, 6-7 
local prefix, 7, 198 
"x" prefix, 7 
namespaces 
discovering, 5 
System.*, 779 
System * namespaces, 5 
using directives, 5 
Windows * namespaces, 5 
native code, compiling programs in, 822 
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On Pointer Pressed method 


NativeOrientation property, 554, 957 
NativeUp program, 555-556 
Navigate method 
calling, 570-571 
in OnLaunched method, 557 
Page Type argument, 557 
NavigatingCancelEventArgs, 564 
navigation 

accelerators, 572-575 
back stack, 562-563 
cancelling, 564 
events, 564-568 

forward and back buttons, 558-560 
with mouse buttons, 572-575 
new page instances, creation of, 561 
of pages, 557-562 
page shared data, 575-581 
state, saving, 568-571 
Visual Studio templates, 581-588 
NavigationCacheMode property, 561-562 
Disabled setting, 564, 566 
Enabled setting, 564, 580-581 
Required setting, 564 
NavigationEventArgs, 564 
NavigationMode property, 564 
■ NET Framework 

APIs, access to, 779 

asynchronous processing support, 242-243 
Dictionary objects, 255 
serialization, 592 
Stream objects, 244, 686 
StreamReader objects, 255 
Task-based Asynchronous Pattern, 222 
New (file) operations, 318 
NewToggle control, 530-535 
class definition, 530 


objects, 35 

defining as fields, 170 
items, controls, adding to, 464 
memory allocations for, 366 
moving in circles, 358-359 
releasing manually, 835 
re-using or caching vs. re-creating, 366 
setting to properties, 34-37 
sharing, 43-47 

sharing through data binding, 66-68 
transforming, 377. See also transforms 
ObservableCollection type, 590-591, 608-611 
Octave.xaml file, 652-653 
Offset property, 94-95 
OffsetX and OffsetY properties, 416 
OLED (organic light-emitting diode) technology, 16 
OnApplyTemplate override, 521, 532 
OnCharButtonClick handler, 167 
OnColorChanged handler, 757 
OnColorChanged method, 171 
OnCreateAutomationPeer override, 184, 890 
OnDragThumbDelta method, 300 
OnGotFocus adn OnLostFocus virtual method, 516 
OnGotFocus and OnLostFocus virtual methods, 140 
OnGotoButtonClick method, 559 
OnlnterpolationFactorChanged method, 999 
OnKeyDown method, 184, 307, 630, 887 
On Key Up method, 184, 887 
OnLaunched method, 557 
Navigate call, 570-571 
SetNavigationState call, 570 
OnLaunched override, 29-30 
OnLoaded method, 315 
On Manipulation Delta method, 660 
OnManipulationStarting override, 677-678 
OnMenuDelete method, 633 


DefaultStyleKey property, 530 OnMessageDialogShowAsyncCompleted method, 225 

dependency properties, 531-532 On methods, 75-76, 615 


NewToggleDemo project, 534 
Newtonian Mechanics (French), 970 
Newton, Isaac, 747, 958 
NextBytes method, 71 
NonAffineStretch project, 442-447 
non-affine transforms, 440-447 


OnNavigatedFrom method, 5, 561, 564 
OnNavigatedTo method, 5, 84, 561, 564 
overriding, 558, 566 
OnNavigatingFrom method, 5, 561, 564 
overriding, 568 
OnPageTapped handler, 79 


notifications of data updates, 194-195 


o 

ObjectAnimationUsingKeyFrames class, 371 
commenting out, 283 
Object class animations, 331, 371-372 


OnPointerCaptureLost method, 630 
overriding, 644-646 
OnPointerMoved method, 620, 733, 759 
overriding, 621, 1027-1028, 1032 
processing, 1016 
OnPointerPressed method, 733 
keyboard focus, 630 

overriding, 620, 1016, 1026-1027, 1031-1032 
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OnPointerReleased method 


OnPointerReleased method 

overriding, 621, 644-646, 1033-1034 
processing, 620 

OnPrintTaskSourceRequested method 
handler, 908-909 
overriding, 942 

OnPropertyChanged method, 196, 198 
OnSaveAsAppBarButtonClick method, 710 
OnSuspending method, 569 
OnTapped method, 140 
overriding, 76-78, 133 
OnTextBlockTapped method, 78 
OnThumbDragStarted method, 300 
Opacity property, 17 
animating, 345-347 
Open buttons, 320-321 
open (file) operations, 318 
OpenlfExists enumeration, 248 
OpenlfExists method, 248 
OpenReadAsync method, 238 
OperationCanceledException exceptions, 253 
OppositelyScaledText project, 397-398 
OptionChanged events, 924-925 
OptionChanged handler, 925-926, 946 
Optionld property, 925 
OrderByDescending function, 255 
Organize Usings command, 24 
OrientableColorScroll project, 152-154 
OrientationAndOrientation project, 955-958 
OrientationChanged events, 87, 554-556, 954 
OrientationChanged handler, 954 
orientation, hardware 

rotating maps with, 1000-1012 
SimpleOrientationSensor, 953-958 
Windows compensation for, 955, 957, 966 
Orientation property, 297, 311, 954 
Horizontal setting, 106, 496-497 
of Slider controls, 143 
of UniformGrid class, 487, 493 
Vertical setting, 130-131 
OrientationSensor class, 980-986 
instantiating, 983 
rotation matrix, 981 
orientation, software, 9, 955 

application awareness, 554-557 
auto-rotation, preventing, 958 
of book pages, 870-871 
detecting, 958-969 
event handling, 87 
layout, adjusting, 152-154 
maintaining, 554 
native, 554 
portrait mode, 550 


preferences for, 957, 966 
preferences, requesting, 556 
saving settings, 308 
Slider control templates and, 521 
of StackPanel, 553 
text reformatting for changes, 19 
OriginalSource property, 74-75, 618 
Oscillations property, 337 
OuterColor property, 698 
OverflowContentTarget property, 862-863 
OverlappedStackedText project, 19-20 
override keyword, 76 

P 

Package.appxmanifest file, 235 
application permissions, 894 
Location capabilities, 672, 999 
Webcam, 772 

Padding property, 100-101, 911 
TemplateBinding on, 510 
Page class, 5 

abandoning instances, 561 
adding to project, 557 
attributes set to, 14 
Content property, 37, 97 
event handlers, attaching and detaching, 561 
Frame property, 557 
Loaded events, 86 
multiple derivatives, 539 
NavigationCacheMode property, 561-562 
new instances, 561 
OnNavigatedFrom method, 561, 564 
OnNavigatedTo method, 561 
OnNavigatingFrom method, 561 
resources, obtaining and releasing, 561 
state, saving and restoring, 564 
TopAppBar and BottomAppBar properties, 268 
PageHeaderTextStyle, 583 
pageHeight value, 920 
PageMapping property, 940-942 
page-navigation structure, 5 
PageNumber property, 910 
pages, 539-612 

ActualWidth and ActualHeight properties, 541 

back stack, 562-563 

back stack, position in, 563 

Border objects, 911 

data, passing and returning, 575-581 

dictionary, sharing, 565 

events, sequence of, 86 

FlipView controls for, 587, 1038, 1043, 1048-1049 
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PathSegment class 


pages {continued) 
initialization, 231 
InkManager for, 1014 
maxPageHeight value, 920 
navigating, 557-562 
new instances, 561 
orientation for printing, 950 
pageHeight value, 920 
pagination, 862-877 
pagination for printing, 915-921 
printable and unprintable areas, 911-914 
print margins, 922 
print preview, 909-910, 920 
ranges of, printing, 937-947 
restoration of, 564-568 
scaling issues, 545-549 
screen resolution issues, 539-545 
size, images and, 10 
snap views, 549-554 
state, saving and restoring, 564 
transforms on load, 409-410 
transition between, 561 
uninitialized, 567 
visual tree on, 97 
page state 

restoring, 568 
saving, 564-565, 568-572 
PaginateEventArgs, 911 
Paginate handler, 909, 914, 915, 934-936 
multiple calls to, 910,917 
printer settings, obtaining, 946-947 
Paginate method, 917-918 
pagination, 862-877 
Canvas for, 921 

maxPageHeight value calculation, 920 
pageHeight value, 920 
of print documents, 915-921 
Panel class 

Children property, 97, 103 
classes deriving from, 7, 484-497 
class hierarchy, 103 
transforms on, 377 
visual children, 450 
panels, 97-138 

Border element, 97-101 

Canvas, 132-136. See also Canvas 

columns in, 131 

custom panels, 484-497 

desired height, calculating, 118-119 

vs. elements, 14 

Ellipse class in, 101-103 

flip panels, 434-437 

horizontal stacking, 106-108 


items, displaying in, 481 
library projects, 127-129 
nesting, 104, 147 
orientation changes and, 97 
overlapping elements, preventing, 137 
page size changes and, 97 
Rectangle class in, 101-103 
scrolling, 112-118 

StackPanel class, 103-106. See also StackPanel 
panel 

VariableSizedWrapGrid panel, 130-131 
virtualizing, 481-484 
Paragraph Alignment enumeration, 884 
Paragraph class, 41, 859-861, 873-875 
ParagraphFormat property, 877 
parallel processing, 222, 243 
Parameter property, 564 
Parent property, 47 
parents 

and children, balancing needs, 97 
layout relationship, 937 
partial keyword, 5 
PassData class, 577-578 
Password Box controls, 184, 187 
Paste buttons, 898-899 
Ctrl+V support, 902 
logic, 900-901 
Paste command, 898 
PasteFromClipboard method, 1037-1038 
Path element, 53-57, 101 
antialiasing, 758 
brushes, applying, 424 
in code, 56-57 
Data property, 53 

drawing smooth lines with, 640-646 
in Grid, 59-60 

as ink stroke rendering elements, 1019-1020, 1022 
Path=, 453 
Stretch property, 55 
tick marks, 403-404 
transforms, applying, 421-422 
PathFigure objects, 53, 54 
PathGeometry class, 53 
constructing, 642 
PathIO class, 243-245 

string URIs, passing, 244 
path markup syntax 

in analog clock program, 403 
geometry, defining, 55-57 
PathMarkupSyntaxCode project, 56-57 
Path property, 68 
PathSegment class, 53 

Point type properties, 361 
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Pause method 


Pause method, 433 
pch.h (precompiled headers) file, 809 
PC Settings, 788 
pen input, 616 

black ink color, 1015 
color of stroke, 1014 
distinguishing, 650 
erasing, 1014, 1023-1029 
erasing, enabling, 1024 

Grid for preliminary lines and Bezier curves, 1023 

PointerEntered events, 650 

Pointer events, 617 

rendering, 1015 

rendering logic, 1033-1034 

text, 1014 

white background, 1015 
PenLineCap enumeration, 178 

RadioButton custom control for, 182 
PenLineJoin enumeration, 178 

RadioButton custom control for, 182 
pens, 1013-1056 

capacitance pens, 1014 
electromagnetic pens, 1014 
existing ink and settings, loading, 1045 
hold-and-release for right-clicking, 632 
InkDrawingAttributes class, 1017-1023 
InkManager class, 1014-1017 
IsInContact property, 1016-1017 
Manipulation events from, 656 
polylines, rendering while drawing, 1023 
Position property, 669 
pressure, 1014-1015, 1019 
pressure, ignoring, 1022 
rendering segments, obtaining, 1019 
selection, 1029-1038 
shape and size of tip, 1014 
tilt and twist support, 1014 
versatility and precision, 1013-1014 
YellowPad program, 1038-1056 
PenTip property, 1017 
Permissions item, 894 
Petzold, Charles 

3D Programming for Windows, 981 
Windows Phone 7.5 astronomy program, 992 
Windows Phone 7.5 sensors articles, 953 
Windows Phone 7 pagination issues, 877 
Petzold.ProgrammingWindows6.Chapterll library 
ArrangeOverride, 492 
ByteToHexStringConverter converter, 470 
CheckedContent and IsChecked properties, 531 
ColorToContrastColorConverter, 494 
Measure call, 490 

MeasureOverride method, 489-490 


NamedColor class, 469-470, 807 
namespace declaration, 471 
panel size calculations, 491-492 
property-changed handler, 487-488 
property definitions, 487-488 
using directive, 471 

Petzold.Windows8.VectorDrawing library 
antialiasing, 758 
ArcSegment structure, 726-727 
IGeometrySegment interface, 724-725 
line drawing on bitmap structures, 724-725 
LineSegment structure, 725 
RoundCappedLine structure, 727-728 
RoundCappedPath structure, 728-730 
Vector2 structure, 638-646 
PhotoFilename property, 595 
photos, capturing, 772-777 
PhotoScatter program, 763-772 

directory structure, displaying, 765-766 

ItemTemplate, 766 

Manipulation events, 769-770 

orientation of items, 764 

Picture library access, permission for, 767 

thumbnails, replacing with bitmaps, 770-772 

Thumbnail type, 769 

zlndex property, 765 

PickSingleFileAsync method, 237-238, 707 
Pictures library, 763-772 
access permissions, 767 
Camera Roll directory, 773 
PieSlice class 

animating, 364-367 
UpdateValues method, 366 
pinch gesture, 112, 655 
P/Invoke (Platform Invoke), 779-785 
argument definition, 782 
data structure equivalence between C# and 
Win32, 780-781 
extern functions, 782, 783 
function declarations, 781-782 
LayoutKind enumeration, 781 
MarshalAs attribute, 791 
StructLayoutAttribute class, 781 
structure definition, 782-783 
wiki website www.pinvoke.net, 786 
wProcessorArchitecture field, 784-785 
PitchDegrees property, 980 
Pivot property, 677, 678 
pixel bits, 684-690 
accessing, 683, 686 
array size, 686 
index, 686 
position of, 689 
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Polyline element 


pixel bits {continued) 

premultiplied-alpha format, 684 
saving as field, 701 
updating, 688 

PixelBuffer property, 683, 686 
PixelHeight and PixelWidth properties, 684 
pixels 

device-independent, 545 
and points, equivalence, 15 
pixels per inch, 539 
pixelStream objects, 694 
Placement enumeration, 264 
PlacementTarget property, 499 
PlaneProjection class, 379, 430-434 

CenterOfRotationX, CenterOfRotationY, 
CenterOfRotationZ properties, 434 
GlobalOffset properties, 434 
LocalOffset properties, 434 
PointAnimationUsing Key Frames class, 368, 370-371 
KeyFrames property, 369 
PointCollection, 49 
PointerCanceled events, 617 
PointerCaptureLost events, 617 
responding to, 628-629 
PointerCaptureLost handler, 1028 
PointerCaptures method, 628 
Pointer class, 618 
PointerDeviceType property, 618 
PointerEntered events, 616, 617, 650-655 
PointerEventArgs class, 617 
Pointer events, 69, 615, 616-619 

dictionary for, 618-619. See also dictionary 
for finger touches, 616-617 
ID number, 615 
logging sequence of, 622-628 
missing data, 628 
for pen input, 617 
tracking fingers with, 615-616 
for XYSlider control, 749-752 
PointerExited events, 616, 617, 650-655 
Pointerld property, 618 
Pointerlnfo class, 622 


finger outside page, 622 
frequency, 637 
LastPoint value, 649 

PointerMoved method, RenderOnBitmap calls, 762 
PointerPoint class, 618 
PointerPoint objects, 1016 
PointerPointProperties class, 619, 633-634, 1014 
IsBarrel Button Pressed property, 1014 
IsEraser property, 1014 
Islnverted property, 1014 
PointerPressed events, 572-573, 616, 617 
CapturePointer calls, 628 
topmost element, association with, 631 
PointerPressed handler, 573, 631 
Pointer property, 618 
PointerReleased events, 616, 617 
missing, 628 

PointerRoutedEventArgs, 617-618,1016 
GetCurrentPoint method, 618 
GetlntermediatePoints method, 618 
Handled property, 618 
KeyModifiers property, 618 
members, 618 

OriginalSource property, 618 
Pointer property, 618 
pointers. See also mouse; pens; touch 

capture by elements, 615, 622-630, 634-635 
capturing, 1023, 1027 
to COM objects, 810 
dictionary information, 1024 
to DirectX objects, 835 
position, calculating, 669 
position, returning, 618 
PointerWheelChanged events, 617 
PointKeyFrame class, 369 
Point property 

animating, 331, 361-363 
of XYSlider, 667 
points, coordinate, 960 
specifying, 135 
Points property, 49-50 
Point structure, 49 


Pointerlnfo structure, 634-635 
pointer input, 615. See also mouse; pen input; touch 
all, supporting, 1016 
Bezier curves, 1018 
on elements, 627 
receiving, 615 
tracking, 628 

PointerLog program, 622-628 
PointerMoved events, 616, 617 
Angle value, 649 

distinguishing between mouse and pen input, 627 


points, typeface, equivalence to pixels, 15 
Point type, 33 
PolyBezierSegment, 1022 
Polygon class, 101, 188 
Polyline element, 48-49,101 
antialiasing, 758 

Bezier curves, converting to, 1021 
creating, 630 
dictionary, adding to, 630 
in finger-painting projects, 619-646 
intializing, 630 
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Polyline element (continued) 


Polyline element {continued) 

Points property, 49-50 
for selection, 1031-1032 
Stretch property, 51 
StrokeThickness property, 634 
whirligig functionality, 647-649 
Popup class, 261, 265-268, 286-293 

with application bars, 285-286, 289-290 
as child of UserControl, 268 
Closed event handler, 327 
dismissing, 267 
displaying popup, 267 

HorizontalOffset and VerticalOffset properties, 267 
IsLightDismissEnabled property, 267, 897 
Opened and Closed events, 292 
positioning, 267 
for Settings list items, 894 
UlElement Child property, 265 
PopupMenu class, 261-264, 632 

with application bars, 285-286, 289-290 
constructing in code, 262 
Opened and Closed events, 292 
popups 

context menus, 261-264. See also context menus 
dismissing, 267, 292, 895, 897 
Popup class, 265-268 
PopupMenu class, 261-264 
positioning, 291 
PortraitBackButtonStyle, 586 
position 

calculating, 972 
two-dimensional, 970 
Position property, 618, 669, 1019 

scaling and rotation centers, determining, 673 
Posterizer program, 714-721 
application bar, 714-716 
control panel, 714-716 
Image element, 714-716 
pixel arrays, 714 

RadioButton event handler, 719-720 
Potter, Beatrix, 119, 937 
PowerEase class, 357 
Power property, 357 

PreconfiguredAnimations project, 373-376 
presentation layer, 193 
Pressure property, 634 

of InkStrokeRenderingSegment, 1019 
stroke thickness based on, 636 
pressure, touch, 1014-1015, 1019 
ignoring, 1022 

PreviewPageCountType enumeration, 948 


PrimitivePad program, 235-240 

Click handler for Open button, 237-238 
file-saving logic, 238-239, 244 
text wrapping option, 239-240 
primitive types, 24,44 
PrintableClassHierarchy program, 915-921 
PrintableTomKitten program, 942-947 
PrintCustomltemListOptionDetails, 944 
PrintDocument class, 904,906 
deriving classes from, 948 
event handlers, 906 
InvalidatePreview method, 927 
PrintDocument method, 909 
printers 

listing, 905, 908 
number of copies, 923 
page orientation, 923 
printable area, 911-912 
printer-specific panes, 909 
resolution, 904, 911 
settings, 909 

setup customization, 922-923 
text-entry fields for, 944-945 
printing, 904-911 

application registration, 904 
asynchronous jobs, 948 
big jobs, 948 
bitmaps, 948-951 
Border objects for pages, 911 
custom properties, 911, 922-927 
enabling, 932-933 
FingerPaint projects, 948-951 
font size, 910 
margins, 911-914 
monthly calendars, 928-936 
number of pages, 909 
page orientation, 950 
page preview, 909-910, 920 
page ranges, 937-947 
pagination process, 915-921 
printable and unprintable areas, 911-914 
StackPanel on pages, 915 
text color, 910 
PrintManager, 904 

obtaining current instance, 904 
PrintMonthlyPlanner program, 928-936 
PrintOrientation enumeration, 923 
PrintPageDescription structure, 911 
ImageableRect property, 911 
PrintPrintableArea program, 912-914 
PrintTask class, 904 

saving as local variable, 922 
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QuinticEase class 


PrintTaskOptionChangedEventArgs class, 925 
PrintTaskOptionDetails objects, 922-923 
PrintTaskOptions class, 904 

GetPageDescription method, 911 
PrintTaskOptions property, 911 
PrintTaskRequest class, 904 
PrintTaskRequested events, 907 
PrintTaskRequested handler, 904-907, 924, 934, 950 
printer setup customization in, 922-923 
private fonts, 847-850 
PrivateFonts project, 847-850 
first column, 849 
font file location, specifying, 848 
referencing files in local storage, 855-856 
second column, 850-852 
third column, 853-854 
private keyword, 71 
private methods, 834 

procedural method calls, interaction between MVVM 
layers, 194 

ProcessNewOrientationReading method, 997 
ProcessorType enum, 785 
ProcessPointerDown method, 1016 
ProcessPointerUpdate method, 1016 
enclosure line, 1029 


in solutions, 3 

promises (future objects), 223 
Propeller project, 395-396 
properties 

attached properties, 132-136 

dependency properties, 15. See also dependency 

properties 

handlers, 223 

linking, 66 

propagating in visual tree, 14 
recursive changes in, 200-201 
setting, 15 

specifying independently of class, 62 
static get-only, 15 
property attributes, 35 
PropertyChangedEventArgs class, 195 
PropertyChanged events, 195-198 

ignoring while setting properties, 211 
property-changed handlers, 173, 195, 209-210, 
487-489 

avoiding, 175-176 
calls to instance handler, 297-299 
property-changed methods, 171 
property elements, 35 

content before or after, 40-41 


ProcessPointerllp method, 1016 
program logo bitmaps, 13 
programs 

compiling and running, 8 
running in simulator, 9 
running outside debugger, 9 
Settings charms, 894-897 
startup, 29-30 
structure of, 221 
terminating, 9 


Tag property, 178 
property-element syntax, 34-37 
quotation marks, 67 
start and end tags, 35 
with Value property, 62 
property inheritance, 21, 63-64 
property initialization, 33 
C# 3.0 style, 24-25 
properties, accessing, 170 
PropertyMetadata constructor, 168-169 


ProgressBar controls, 527 
Value property, 141-142 
Progress objects, 254 
ProgressRing controls, 142 
Project Gutenberg, 119, 346 
Projection class, classes deriving from, 379 
ProjectionMatrix property, 439 
Projection property, 377 

setting to derivatives of Projection class, 379 
projection transforms, 380, 430-437 
projects, Visual Studio 
Assets folder, 9, 13 
bare essentials for, 29-30 
files in, 4 

images, adding, 12 
Images directory, 12 
platform options, 823 
platform, specifying, 822-824 


PropertyName property, 195 

Property property, 171, 173 

protected constructors, 117 

pseudo-3D transforms, 380. See also projection 

transforms 

public constructors, 832 
public methods, 835 

Q 

quadkey numbering, 1006-1009 
QuadraticBezierSegment class, 361 
QuadraticEase class, 357 
QuarticEase class, 357 
quaternions, 981 
QuickNotes project, 249 
QuinticEase class, 357 
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RadialGradientBrushDemo project 


R 

RadialGradientBrushDemo project, 696-703 
dependency properties, 696-698 
MainPage.xaml file, 702 
RefreshBitmap method, 699-701 
RadialGradientBrushSimulator class, 696-702 
animating, 702 
instantiating, 702 
radians variable, 50 
RadioButton controls, 161, 177-183 
in Border, 161 
Checked handlers, 265, 274 
Content property, 160 
creating, 716 
customizing, 182-183 
GroupName property, 161 
managing, 325-327 
properties, setting, 180-181 
styling, 285 
Tag property, 576 
in UserControl, 289 
RainbowAnimation project, 369-370 
RainbowEightTransform project, 423-427 
RaiseCanExecuteChanged method, 214 
RandomAccessStreamReference, 244 
creating, 900 

Random objects, NextBytes method, 71 
RangeBase controls, 141 
RangeBaseValueChangedEventArgs, 143 
ranges, Slider controls for, 142-145 
raster lines, 723 
ReadBufferAsync method, 244 
ReadingChanged handler, 959 
ReadLinesAsync method, 243 
Read methods, 238 
ReadTextAsync method, 243 
ReadTextAsync method calls, 248 
RecalculateValue method, 669 
Rectangle class, 101-103 
properties of, 103 

RectangleGeometry transforms, 421-422 
redraw methods, 303 
RedrawRuler, 305 
reentrancy, 319 
ref keyword, 810-811 
ReflectedAlphalmage project, 692-695 
ReflectedFadeOutlmage project, 398-400 
reflection, 113-114 

in easing animations, 354 
obtaining properties, 468 
simplifying, 129 

updating properties when properties change, 796 


ref new keyword, 810-812 
RefreshBitmap method, 698-701 
RefreshDisplay method, 1010-1011 
RegisterAttached method, 168 
Register method, 168 
RelativeSource bindings, 506 
syntax, 480 

RelativeSource markup extension, 68, 204 
RelativeTransform property, 422 
ReleasePointerCapture method, 628 
ReleasePointerCaptures events, 629-630 
ReleasePointerCaptures method, 628 
Remove method, 567 
Remove Unused Usings command, 24 
RenderAII method, 1033 
RenderBeziers method, 1034-1036 
Rendering events, 329, 802 
handling, 841 
for long-running jobs, 250 
Rendering handler, 92-93, 95-96 
RenderOnBitmap method, 729-731, 759-762 
RenderStroke method, 1034-1036 
RenderTarget property, 1040 
RenderTransformOrigin property, 377, 384, 387, 396 
400 

specifying, 420-421 

RenderTransform property, 377, 382, 387 
setting to Transform derivative, 378, 379 
TransformGroup setting, 673 
RepeatBehavior attribute, 335-336, 341 
RepeatButton controls, 161 
RequestedTheme attribute, 16 
resolution 

of printers, 904, 911 
scaling and, 545 
for snap modes, 551 
Resolve command, 23 
ResourceDictionary class, 43 
as root element, 46 
resources 

binding converters, 111-112 
ControlTemplate as, 503 
defining, 46 
including in projects, 47 
predefined, 47 

referencing in bindings, 198-199 
sharing, 43-48 
templates as, 449 
View Model as, 198, 206 
Resources collection, accesing objects in, 204 
Resources dictionary 
keys, 46 

placement in XAML file, 46 
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Resources dictionary {continued) 
referencing from code, 47 
retrieving items, 47 
x:Key attribute, 44 
Resources property, 43-44, 44, 387 
Resources section 

animation definitions in, 330 
classes in, 198 

DataTemplate definition in, 454 
Merged Dictionaries property, 273 
StandardStyles.xaml, 271 
Resume method, 433 
Resuming events, 246-247 
logging, 247-248 

retained mode graphics system, 83 
ReturnData class, 578 
reverse painting, 758-762 
ReversePaint program, 758-762 
RgbBarChart project, 497-499 
RGB (red, green, blue) color, 17 

HSL, conversion routines, 747-749, 755-756 
RgbViewModel class, 198 
RichEditBox controls, 184, 877-886 
file loading and saving option, 877 
rich text, 845. See also text 
Glyphs element, 850-852 
paginating, 862-877 
paragraph formatting, 858-861, 872-875 
private fonts, 847-850 
RichEditBox, 877-886 
RichTextBlock, 858-861 
text input, 887-892 
text selection, 862 

typographical enhancements, 856-858 
RichTextBlock element 
Blocks property, 858 
ContextMenuOpening events, 862 
HasOverflowContent property, 862 
InlineUIContainer and, 861 
Measure pass, 862, 869 
OverflowContentTarget property, 862-863 
pagination and overflow, 862-869 
paragraphs, 858-861 
repaginating on orientation changes, 871 
in ScrollViewer, 859-861 
SelectedText property, 862 
SelectionChanged events, 862 
SelectionEnd property, 862 
SelectionStart property, 862 
SizeChanged handler, 868 
RichTextBlockOverflow element, 862-869 
adding and removing as needed, 875 
generating in code, 867 


HasOverflowContent property, 862 
hidden, 866 

OverflowContentTarget property, 862 
repaginating on orientation changes, 871 
RichTextColumns class, 867 
RichTextEditor project, 878-887 

Bold, Italic, and Underline properties, 883 
ComboBox handler, 884 
file-saving and loading logic, 885-887 
FontStyle property, 883 
FormatRtf flag, 886 

LoadFromStream and SaveToStream methods, 882 
paragraph formatting, 882, 884 
Suspending handler, 880, 882 
text formatting buttons, 880 
text-formatting items, initializing, 882-883 
right-hand rule, 960 
RightTapped events, 69, 262, 615 
RightTapped handler, 262, 265-267, 631 
Ritchie, Dennis, 3 

RotateAroundCenter project, 384-386 
rotate gesture, 655 
RotateTheText project, 381-384 
RotateTransform class, 379 
Angle property, 378, 380 
CenterX and CenterY handlers, 385 
CenterX and CenterY properties, 383-384 
RenderTransform property, 382 
transform formulas, 415 
RotatingMap program, 1000-1012 

longitude and latitude calculations, 1007-1008 
MainPage constructor, 1002 
map tiles, 1000-1002 
number of tiles to display, 1009 
quadkey construction, 1008-1009 
Web service access, 1003-1004 
zoom buttons, 1011-1012 
rotation, 380-386 

2D elements in 3D space, 378, 431 
angle of, calculating, 841 
Angle property, bindings on, 380-381 
around Z axis, 968 
centered, 673-676 

center of rotation, 378, 383-386, 391-396 

composite transforms, 391 

direction of, 431 

of images, 392-393 

of images at save, 712-714 

MatrixTransform for, 417 

origin, 383 

RenderTransformOrigin property, 384 
single-finger, 676-682 



rotation (continued) 


rotation {continued) 

three-dimensional, 379, 976-986. See also three- 
dimensional rotation 
transform formulas, 411-412 
rotation axis, 379-380, 431 
RotationBehavior property, 664 
RotationCenterDemo project, 394-395 
rotation matrices, 981 
rotation of device, counteracting, 555 
RotationX, RotationY, RotationZ properties, 431 
animating, 431-434 
RoundCappedLine structure, 727-728 
RoundCappedPath structure, 728-730 
RoutedEventArgs class, 75 
routed event handling, 72-78 
OriginalSource property, 75 
RoutedEvent property, 360 
routed events 


s 

Samsung 700T tablet, 1013-1014 
SensorRotationMatrix, 981 
Save As buttons, 318-319 
Save As dialog box, 318 
Save buttons, 318-319 
SaveState method, 581 
SaveStatePage class, 565-568 
SaveToStream method, 882, 886 
ScalablelnternationalHelloWorld program, 87 
Scale property, 660 
ScaleToBitmap method, 731 
ScaleTransform class, 379, 396-400 

CenterX and CenterY properties, 398, 411 
ScaleX and ScaleY properties, 396, 411 
transform formulas, 411, 415 
scale transforms, 396-400 


Pointer events, 617 
PointerPressed events, 631 
RoutedEvents projects, 72-83 
AddHandler method, 79 
event handlers, sharing, 72-73 
Grid background color changes, 76-77 
HorizontalAlignment and VerticalAlignment, default 
values, 81-82 

no event handlers in XAML file, 75 
OnTapped method, 76 

OnTextBlockTapped method Handled property, 78 
separate processing for events, 80-81 
Tapped events on TextBlocks, 77 
Tapped handler on parent element, 74 
RoutedEvent type, 79 
routed input handling, 74-75 
RowDefinition objects, 146 

MinHeight and MaxHeight properties, 147 
RowDefinitions collection, 146 
RTF files, 877 

loading and saving, 882 
RudimentaryTextBox control, 888-892 
OnCreateAutomationPeer override, 890 
RulerContainer controls, 301 
Child property, 301 
RunAsync method, 225 
Run class, 42 

mimicking with TextBlock elements, 108-110 
Text property, 41-42 
Run method, 250 
Run property, bindings on, 87-89 


center point, 398 
composite scaling formulas, 411 
negative scaling factors, 398 
skew, combining with, 419-421 
ScaleX and ScaleY properties, 396 
scaling, 545-549, 993 
centered, 673-676 
isotropic scaling, 660, 674 
scaling center, 398, 411 

for touch elements, 673-676 
scan lines, 723-724 

horizontal boundary lines, 725 
updating, 731 
screen resolution, 539-545 
scRGB color space, 17 
ScrollBar controls, 112 
template for, 142 
Value property, 141-142 
visibility, 113 
scrolling 

horizontal, 113,131, 496, 598 
ScrollViewer for, 114 
vertical, 113, 119, 496 
ScrollViewer, 112-118 
Content property, 112 
desired height, calculating, 118-119 
HorizontalAlignment setting, 123 
inertia and bounce, 114 
ItemsControl in, 465-466 
in ListBox controls, 477-478, 483-484 
pinch interface, 112 
RichTextBlock in, 859-861 
in TextBox controls, 185 
sealed keyword, 129 
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Settings charms 


secondary threads, 221,224 
animations in, 331 
long-running jobs in, 250 
transform animations in, 382 
SecondPage class, 557-559, 566 
Seek calls, 687 
Segments property, 53 
SegoeSymbols project, 277-283 
characters, specifying, 282 
DoubleToStringHexByteConverter class, 278 
Grid, 278-280 
ValueChanged handler, 281 
Segoe Ul Symbol font, 271-272, 276-283 
emoji characters, 276 
emoticon characters, 277 
folder icon, 767 


Selectorltem class, 535 
SelectWithLine method, 1029 
SelectWithPolyLine method, 1029 
semantic zoom, 582 
sender argument, casting, 72, 73, 151 
SensorQuaternion class, 980-981 
SensorRotationMatrix class, 980-981 
as identity matrix, 981 
sensors, 953-1012 

accelerometer, 958-969 

Compass, 974-976 

Geolocator, 999-1012 

of horizontal coordinate, 987-999 

inclinometer, 976-980 

of magnetic north and true north, 974-976 

members, 959 


miscellaneous symbols, 276 
Style definitions, 272 
transportation and map symbols, 277 
Selectedlndex property, 476 
Selectedltem objects, 479 
Selectedltem property, 476 
as binding source, 477 
Selected property, 1029 
SelectedText property, 184, 862 
SelectedValuePath property, 478-479 


OrientationSensor, 980-986 
SimpleOrientationSensor, 953-958 
software interface, 959 
serialization, 592 
set accessors, 26, 170 
functionality, 201 
protected, 198, 200, 311 
public, 202-204 
SetProperty calls, 202 
SetBinding method, 67 


SelectedValue property, 477, 479 
selection 


SetBitmap method, 899-900 
SetBubble method, 968 


highlighting, 535 

item clicking, enabling, 599 


SetContent method, 899 
SetCrossHair method, 669 


in ListViewBase, 599 


SetDefaultDrawingAttributes method, 1018 


of pen input, 1029-1038 
selected items, highlighting, 1029 
by swiping, 582 
vs. tapping, 476 
turning off, 599 

SelectionChanged events, 185, 477, 862 
handling, 876 
of RichTextBlock, 862 


SetDefaultXamIFile method, 315 
SetNavigationState method, 568-569 
SetPixelData method, 712 
SetPreviewPageCount method, 910, 948 
SetPreviewPage method, 910 
SetProperty method, 202 
SetSource method, 683, 692 

IRandomAccessStream objects, passing in, 694-695 


SelectionEnd property, 862 


SetTarget property, 339 


SelectionMode property 


Setter class 


Extended setting, 480 
Multiple setting, 480, 599 
None setting, 599 
Selection property, 877 

SelectionStart and SelectionLength properties, 184- 
185, 862 

SelectionStates group, 536 
Selector class, 464, 535 

Selectedlndex property, 476 
Selectedltem property, 476 
SelectedValue property, 477 
SelectionChanged events, 477 


for controls, 503 
tags, 61 

Value property, 62 
settings 

precedence of, 63 
storing, 308. See also applications 
SettingsAppBarButtonStyle style, 286 
Settings button, 286 
Settings charms, 894-897 

commands, adding to Settings pane, 896 
PC Settings program, 520 
Permissions item, 894 
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SettingsDialog class 


SettingsDialog class, 322-327, 804-807 
SettingsPane class, 896 
Show method, 896 
SetValue method, 26 
calling, 135 
Shaken events, 966 
Shape class, 48 

classes deriving from, 101 
Fill property, 101 
Stretch property, 51, 58, 102 
Stroke property, 101 

StrokeStartLineCap, StrokeEndLineCap, and 
StrokeLineJoin properties, 177 
StrokeThickness property, 101 
shapes, filling, 723-724 
Shapes library, 48 
Share charm, 898-902 
hooking into, 903 
Share providers, 903 
SharedBrush project, 44-47 
SharedBrushWithBinding project, 66-68 
SharedBrushWithStyle project, 60-64 
Resources section, 60-61 
SharedStyleWithDataTemplate project, 455-456 
Share Targets, 903 
SharpDX library, 808 
shearing, 406 

ShowAsync method, 221-223, 263, 632 
Point value, 263 

ShowForSelectionAsync method, 264 
Show method, 896 
ShowPrintUIAsync calls, 929-930 
SilasMarner program, 870-877 
page fraction, 872 
Simonyi, Charles, 780 
SimpleAnimationCode project 
Click handler, 339 
XAMLfile, 338 

SimpleAnimation project, 330-333 
SimpleColorScroll project, 148-151 
SimpleCompass project, 974-976 
SimpleContextDialog project, 265-268 
SimpleContextMenu project, 262-264 
SimpleEllipse project, 101-102 
SimpleHorizontalStack program, 106-108 
Simplelnking program, 1015-1022 
SimpleKeyFrameAnimation project, 367-369 
SimpleKeypad project, 163-167 
SimpleListBox project, 477-478 
SimpleOrientation enumeration, 954 
SimpleOrientationSensor class, 953-958 

Accelerometer, correspondence between, 965 
current orientation, 954 


Display Properties.CurrentOrientation, 
correspondence between, 957 
GetDefault method, 954 
instantiating, 953-954 
instantiating as field, 956 
SimplePageNavigation project, 557-562 
forward and back buttons, 558-559 
SimpleProjection project, 379-380 
SimpleRotate project, 378 
SimpleVerticalStack program, 103-105 
SineEase function, 358 
SingleFingerRotate project, 677-678 
singleton pattern, 474 
SizeChangedEventArgs, 85 
SizeChanged events, 84-85 
SizeChanged handler, 84, 190, 540-541, 742-743, 
873-876 

in code, 85 
for Grid, 303 

SkewPlusSkew project, 407-409 
SkewSlidelnText project, 409-410 
SkewTransform class, 379, 406-409 

AngleX and AngleY properties, 406-409 
transform formulas, 412, 415 
skew transforms, 406-409 

scaling, combining with, 419-421 
transform formulas, 412 
SliderBindings project, 144-145 
Slider controls, 139, 141-145, 154-157 

Background and Foreground properties, 145, 754 

barebones template, 522-524 

bindings to Value properties, 144-145 

Control 丁 emplate, 754 

default height and width, 143 

default manifestation, 142 

default range, 143 

IsDirectionReversed property, 145 

LargeChange property, 145 

manipulating, 143-144 

Margin properties, 158 

Minimum and Maximum properties, 143, 158, 278 

Orientation property, 143 

sketching with, 157-159 

SmallChange property, 145 

spring-loaded slider, 524-527 

StepFrequency property, 145 

template for, 521-529 

thickness, 143 

Thumb, 523 

ThumbToolTipValueConverter property, 155-157 
TickFrequency and TickPlacement properties, 145 
tooltips, 154-157 
ValueChanged event, 140, 143 
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Slider controls {continued) 

ValueChanged event handler, 142, 151, 156, 281 
Value property, 141-142, 142, 143 
width, 523 

SliderEvents project, 142-143 
SmallChange property, 145 
smart pointers, 810 
Smooth Bezier, 345 
smoothing 

line taper, 637-646 
movement, 970 
SnappedBackButtonStyle, 586 
SnappedPageHeaderTextStyle, 583 
snap views, 495, 549-554, 604 
adjusting to, 154 
landscape mode, 551 
Snapped state, 583 
SolidColorBrush, 31 
animating, 361 
bindings on, 472, 478 
Color property, 157 

definitions in themeresources.xaml, 520 
Highlight color, 47 
inXAML, 34 
Solution Explorer 

library projects, adding, 127 
project files, 3 
solutions, Visual Studio 

Intermediate Language, compiling in, 822 
libraries, adding, 127, 130-131 
projects in, 3 
referencing, 470-471 
Solution Name, 3 

SourcePageType property, 564, 579 

Source property, 13, 27, 28, 199, 200, 609-611, 831 

Span class 

Inlines property, 42 
shortcut classes, 42-43 
SpeedometerProgressBar project, 527-529 
SpeedRatio property, 337-338 
SpinPaint project, 836-843 
Spiral program, 49-51 
SplineColorKeyFrame class, 371 
SplineDoubleKeyFrame class, 371 
SplinePointKeyFrame class, 369, 371 
Split App projects, 539, 581, 867 
SplitContainer class, 295 

bindings to the Orientation and 
SwapEdit And Display properties, 313 
Split method, 710 
SpreadMethod setting, 425 
Springiness property, 337 
SpringLoadedSlider project, 524-527 


SquaringTheCircle project, 361-363 
sRGB (standard RGB) color space, 17 
stack, 562 

StackPanel panel, 103-106 
background, 105 
border, 266 
building, 123-124 
Buttons in, 265-266 
centering, 123 

children, arrangement of, 97, 105 
children, sizing, 487 
desired height, calculating, 118-119 
displaying items in, 482 
height, 107-108 

HorizontalAlignment and VerticalAlignment 

properties, 105-106, 108 

horizontal stacking, 106-108 

Image elements in, 119-122 

lists, displaying, 258-260 

MaxWidth property, 121 

nesting, 123-124 

orientation, 553 

Orientation property, 106-107 

RadioButtons in, 266 

scrolling, 112-118 

text wrapping, 119 

vertical stacking, 103-105 

width, 106 

StackPanelWithScrolling project, 113-115, 118 
StackPanel in ScrollViewer, 113 
StandardPrintTaskOptions class, 923 
StandardStyles.xaml file, 46, 60, 271 

application bar button styles, listing, 273-276 
BackButtonStyle, 585 
font, font color, and font size styles, 878 
PageHeaderTextStyle, 583 
PortraitBackButtonStyle, 586 
SettingsAppBarButtonStyle style, 286 
SnappedBackButtonStyle, 586 
SnappedPageHeaderTextStyle, 583 
TextBlock styles, 65 
Start Debugging command, 8 
StartPoint property, 33 
StaticResource markup extension, 44, 46, 61 
StepFrequency property, 145 
Stop Debugging command, 9 
Stop method, 433 
storage 

application isolated storage, 249, 308 
application local storage, 234. See also application 
local storage 
bulk access, 235 


StorageFile objects 


StorageFile objects, 234, 237 
ContentType field, 711 
creating, 249, 736 
StorageFolder class, 234 

GetFilesAsync method, 767 
StoreAsync method, 239 
Storyboard class 

animating children of, 331 
AutoReverse property, 350 
Begin method, 433 
Children property, 337 
class hierarchy, 337 
duration, 350 
Pause method, 433 
RepeatBehavior property, 350 
Resume method, 433 
reusing in animations, 339 
SetTarget property, 339 
Stop method, 433 
TargetName property, 331, 337 
TargetProperty property, 331, 337 
TargetProperty property, animating, 347-350 
triggering, 332, 359 
Triggers section, defining in, 372 
in visual states, 516 
Stream objects, 237 
disposal, 238 

loading and saving to, 877 
saving as field, 701 
writing byte array to, 686-687 
StreamReader objects, 255 
StretchDirection property, 59 
StretchedSpiral project, 51-52 
Stretch property, 10-11, 51, 52, 55, 58 
None setting, 11, 104, 994 
of Shape class, 102 
Uniform setting, 10-11, 102, 104-105 
UniformToFill setting, 11-12, 102 
Stretch settings, 98 
String class, 812 
Split method, 710 
strings, special characters, 17-18 
Stripped Down Hello project, 29-30 
StrokeDashArray property, 343, 403 
StrokeDashCap property, 343 
StrokeDashOffset property, animating, 343-344 
StrokeEndLineCap property, 177-183, 636 
StrokeLineJoin property, 177-183 
Stroke property, 49, 101 
strokes 

rendering, 1033-1036 
selecting, 1029-1038 

StrokeStartLineCap property, 177-183, 636 


StrokeThickness property, 49,101, 634 
animating, 342-343 
calculating, 345 

StructLayoutAttribute class, 781 
StudentBody class, 590-591 

accessing through bindings, 597 
Students property, 595 
StudentBody Presenter class, 592-594, 611 
instantiating, 594 
StudentBody property, 594 
StudentBody property, 594 
Student class 

FullName property, 595 
PhotoFilename property, 595 
StudentGroup class, 609 
StudentGroups class, 609-611 
Student objects, displaying, 596 
Students property, 595 
Style class, 60 

BasedOn property, 63 
for controls, 141 
ControlTemplate as, 506-507 
for custom controls, 530 
default, 520 

on ItemContainerStyle property, 536 
for ListBox items, 536 
Setter tags, 61 
TargetType attribute, 61 
Template property, defining, 503 
templates defined in, 455 
templates, referencing, 500 
x:Key attribute, 61, 64 
styles, 60-65 

AppBarButtonStyle style, 271-276 

App.xaml, definitions in, 937 

brushes, defining with, 62 

defining in code, 62 

dependency properties, targeting, 63 

for images, 120-121 

for text, 120-121 

implicit styles, 64-65, 68, 459, 530 

inheritance of property settings, 63-64 

keys, 64 

referencing, 61 

SettingsAppBarButtonStyle, 286 
sharing, 43 
TextBlock styles, 65 
StyleSimulations enumeration, 851 
stylus, 1013. See also pens 
Surface!mageSource class, 808 
line drawing on, 831-843 
SurfacelmageSourceRenderer class, 831-836, 838 
surrogates, 277, 281 
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text. See also fonts; rich text 


Suspending Deferral objects, 248 
Suspending events, 246-247, 288 
logging, 247-248 
Suspending handler, 571-572, 880 
SuspendResumeLog program, 247-248 
SuspensionManager class, 581 
suspension, saving settings on, 742 
SwapEditAndDisplay property, 311 
swiping, 599 
disabling, 599 

SystemlnfoPInvoke project, 782-785 
SYSTEMJNFO structure, 780 
System. 10 namespace, 233 
Path class, 57 

System * namespaces, 5, 779 

System.Runtime.InteropServices namespace, 781 

System.Runtime 

.InteropServices.WindowsRuntime namespace, 686 
System.Threading.Tasks namespace, 222 
SYSTEMTIME structure, 788 
SystemTimeToTzSpecificLocalTime function, 788 



TabbableTextBox class, 306-307 

GetPosition From Index method, 307 
IsModified property, 307 
Tab key 

detecting press of, 306 
keyboard input focus, 144 
navigating with, 140, 268 
tablets 

compass orientation, 974-976 
coordinate system, 960 
display sizes, 549 
geographic location, 999-1012 
orientation indicators, correspondence 
between, 957 
SensorRotationMatrix, 981 
sensory hardware, 953-1012 
yaw, pitch, and roll angles, 976-980 
TabSpaces property, 307, 325 
Tag property, 167, 177-183 
as property element, 178 
setting, 182 

TapAndShowPoint project, 133-136 
TappedEventHandler, 70 
TappedEvent property, 79 
Tapped events, 69-72, 615 
Tapped handler, 72-73, 475-476 
Tapped Routed Event Args class, 74-75 
OriginalSource property, 74 


tapping 

positioning elements at, 133-135 
vs. selecting, 476 

TAP (Task-based Asynchronous Pattern), 222 
TapTextBlock program, 70-72 
TapToFlip project, 434-437 

Storyboard definitions, 435-436 
TargetName property, 331, 337 
target properties of animations, 330 
releasing, 334 

TargetProperty property, 331, 337 
animating, 347-350 
TargetType property, 61, 65, 503, 504 
TaskCanceledException exceptions, 232 
Task class, 222, 242 

AsAsyncAction method, 243 
Run method, 250-251 
Run method with await operator, 256 
WaitAII method, 1004 
Yield property, 259-260 
tasks 

cancelling, 252 
progress, reporting, 253-254 
Task<string> type, 242 
TemplateBinding markup extension, 68, 506 
on Background property, 508 
Templated Control projects, 530 
TemplatedParent, 480 
Template property 

of Control class, 139, 502, 503 
as property element, 503 
templates, 329, 449 

binding converters in, 462 

button visual states, 513-520 

ControlTemplate class, 502-512 

default, 520 

empty tags in, 515 

generic.xaml file, 520-521 

for ItemsControl derivatives, 535-538 

layout-aware, 539 

named parts, 521 

selected states, defining, 536 

sharing, 454 

for Slider controls, 521-529 
Style, defining in, 455 
Style, referencing in, 500 
visuals, dynamically updating, 456 
Windows Runtime Component, 808-809 
Tenniel, John, 345, 859 
text. See also fonts; rich text 
animating, 330-333 
ASCII character codes, 277 
centering, 8-9 
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text (continued) 


text {continued) 

character formatting, 880 
characters, spacing, 850, 852 
columns, 866 
compressing to fit, 794 
as content, 18-19 

cut, copy, and paste interaction, 185 

displaying, 7 

font metrics, 824-831 

font-related properties, 845 

font size increases and decreases, 288-289 

formatting, 41-43 

high-performance display, 809-821 

indentation, 121 


in constructor of MainPage class, 24 
documentation, 15 
embedding, 861 

FontFamily property, 845, 847-848 
Foreground property, 16, 31 
formatting features, 42-43 


height, 58 

HorizontalAlignment attribute, 8, 81 
with Inlines collection, 42 
Inlines property, 41 
IsHitTestVisible property, 72 
IsTapEnabled property, 72 
Margin property, 100-101, 121 
Measure method, 305 
orientation changes, 9 
Padding property, 101, 911 
paragraphs in, 119-122 
positioning, 306 
rendered size, obtaining, 305 
Run objects, mimicking, 108-110 
TextAlignment property, 82 
text as content, 18 

text string size, calculation of, 824, 828 
TextWrapping property, 119 
VerticalAlignment attribute, 8-9, 81 
in Viewbox, 494 
Visibility property, 72 
Width and Height properties, 9 
TextBox controls, 184-187 
AcceptsReturn property, 185 
binding behavior, 208-209 
context menu, 262 
InputScope property, 185 
IsReadOnly property, 185 
multiline, 185-187 
page state, saving, 565 
read-only, 247 
ScrollViewer in, 185 
SelectedText property, 184 
SelectionChanged events, 185 
SelectionStart and SelectionLength 
properties, 184-185 
TextChanged events, 140, 185 
Text property, 184-185 
TextWrapping property, 185 
updating with event handlers, 209-211 
TextBoxInputScopes program, 185-187 
TextChanged events, 185 
TextChanged handler, 209-211, 308 
text characters 

hexadecimal specification, 17 
Unicode specification, 17 
TextEffects project, 388-390 
TextElement class, 41 
TextFormattingAppBar project, 283-286 
TextFormatting project, 42-43 
Textlndent property, 859 
text input, 887-892 
Text objects, 307 


indenting first line, 859 
line breaks, 19, 43 
listing, 273-276 

orientation changes, reformatting for, 19 

overlapping, 19-20 

page numbers, 871-873 

paginating, 862-877 

paragraph formatting, 858-861, 872-875 

pasting into Visual Studio, 17 

precise layout, 921 

rich text, 845 

scaling, 397-398, 545 

scrolling, 859-861 

selecting, 862 

shadowing, 829-831 

spacing between paragraphs, 859 

stacking, 19-20 

text-enhancing attached properties, 856-858 
tilting, 829-831 
translation effects, 388-391 
underlining, 278, 285 
validating, 210 
wrapping, 119, 239-240, 861 
TextAlignment property, 18, 82, 858 
Center setting, 84 
TextBlock content property, 41-43 
TextBlock element, 7 

ActualWidth and ActualHeight properties, 305-306 

aligning, 856 

background, 71 

bindings on, 472 

in Border, 98-101, 165 

class derivation, 14 
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TextOnCanvas project, 132-133 
TextPointer type, 862 
Text property, 18, 41-42, 184-185 
Textwrapping property, 18, 289-290 
Wrap setting, 119, 185 
ThemeAnimation animations, 373 
themeresources.xaml file, 520 
themes, 128 
Themes folder, 530 
TheTaleOfTomKitten project, 119-122 
ThicknessSettingDialog class, 743-746 
Thickness type, 100 
this prefix, 27 
ThreadPool class, 250 
threads 

for execution, 221, 224 

Ul thread, 221, 223-225. See also Ul thread (user- 
interface thread) 

ThreeDeeSpinningText program, 431-434 
three-dimensional graphics, 379, 438-447 
coordinate system, 960-961 
fade-out, 398-400 
light source, 388 
perspective, 438 
reflection effects, 398 
three-dimensional rotation, 980-986 
around 3D vector, 981-986 
yaw, pitch, and roll angles, 976-980 
3D Programming for Windows (Petzold), 981 
ThrowlfCancellationRequested method, 252 
Thumb controls, 187-192 

DragStarted and DragDelta event handlers, 188 
DragStarted, DragDelta, and DragCompleted 
events, 187-188, 190 
event handlers for, 300-301 
in non-affine transforms, 444-446 
in XamICruncher, 295 
Thumbnail property, 769 
ThumbToolTipValueConverter property, 155-157 
Tick events, 89 

TickFrequency and TickPlacement properties, 145 
Tick handler, 91 
tiles, program, 9 
tilt 

calculating, 990-992 

effect on acceleration, velocity, position, 969-972 
TiltAndBounce program, 972-973 
TiltAndRoll program, 969-972 
TiltedShadow program, 419-421 
TiltX and TiltY properties, 1019 
time 

conversions between time zones, 788 
converting between programming platforms, 793 


local time, 787-788 
local time, obtaining, 802 
UTC time, converting to local, 792 
time, elapsed, 92 
Timeline class 

AutoReverse property, 349 
Completed event, 338 
properties of, 337 
RepeatBehavior property, 349 
SpeedRatio property, 337-338 
TimelineCollection type, 337 
timer events, handling, 89-96 
TimeZoneClock class, 794-797 
TimeZonelnfo class, 789 
TIME_ZONE_INFORMATION structure, 787 
SYSTEMTIME structure, 788 
TimeZoneKeyName field, 792 
TimeZoneManager class, 789-791 
constructor, 791 
time zones 

enumerating, 787 
registry settings, 788 
Windows 8 settings, 788 
ToggleButton controls, 161, 239-240 
Checked and Unchecked events, 161 
indeterminate state, 161 
IsChecked property, 161 
IsThreeState property, 161 
ToggleSwitch controls, 161 
Header property, 325 

OnContent and OffContent properties, 325 
ToolTip controls, 499 

PlacementTarget property, 499 
tooltips 

formatting, 155-157 
in Slider controls, 524 
TopAppBar property, 268 
ToString, 451 
touch 

centered scaling and rotation, 673-676 
contact area bounding box, 633 
editing features, 630-633 
finger movement, tracking, 618 
FingerPaint projects, 619-646 
inertia, 187, 661, 663-667 
line tapers, smoothing, 637-646 
Manipulation events, 655-663 
pointer capture, 622-630, 634-635 
Pointer events, 616-619 
pointer input, 615. See also pointer input 
Position property, 669 
pressure sensitivity, 633-637 
right-clicking equivalent, 632 


touch (continued) 

touch (continued) 

saving drawings, 646 
single-finger rotation, 676-682 
surreal renderings, 647-649 
text selection, 862 
touch piano project, 649-655 
XYSlider control, 667-672 
Touchlnfo class 
Angle value, 649 
LastPoint value, 649 
touch keyboard, 184 
input from, 888 
invoking, 890 
types, 185 
To value 

adjusting on Canvas size, 703 
of DoubleAnimation, 424 
TransformBounds method, 427, 430 
Transform class 
animating, 347 
classes deriving from, 379 
TransformGroup class, 379, 391-396 
Children property, 391 
matrix multiplication, 418 
Matrix value, 427 
Value property, 674 
Transform method, 418 
TransformPoint method, 427 
Transform property, 53 
of Brush class, 422 
of Geometry class, 421 
transforms, 377-447 
affine transforms, 379 
analog clock project, 400-405 
brush transforms, 422-427 
cascading, 401 

composite transform formulas, 411 
composite transforms, 418-421 
final location, 409-410 
flip panels, 434-437 
geometry transforms, 421-422 
grouping, 391-396 
homogenous coordinates, 414 
mathematics, 410-418, 437-447 
Matrix3D, 437-447 

matrix multiplication, 413-416, 437-447 
matrix transform formulas, 414, 437-447 
matrix transform, specifying, 416 
non-affine transforms, 440-447 
order of, 418-421 
origin, 400 

on page load, 409-410 


projection transforms, 430-437 

rotation, 380-386 

rotation axis, 378, 379-380 

rotation transform formulas, 411-413, 415 

scale transform formulas, 415 

scale transforms, 396-400 

in secondary threads, 382 

skew, 406-409 

skew transform formulas, 412, 413, 415 
standard matrix representation, 414 
three-dimensional effects, 379 
translation, 388-391 
translation formulas, 413-415 
two-dimensional affine transforms, 440 
as visual feedback, 386-387 
TransformToVisual method, 291, 427-430 
Transition class, animations deriving from, 375-376 
TransitionCollection type, 375 
Transitions property, animating, 375 
TranslateTransform class, 379, 388-393 
To value of DoubleAnimation, 424 
transform formulas and translation factors, 411, 415 
X and Y properties, 388, 394 
translation, 388-391 
Translation Behavior property, 664 
Translation property, 660 
transparency, bitmap, 691-696 
Triggers property, 359-360 
defining on Path, 361 
Triggers section 

animation definition in, 372 
Storyboard definition in, 372 
try and catch blocks, 233 
await operator in, 230, 232 
file access in, 258 
TryParse method, 211 
TryUnsnap method, 554 
.TTF (TrueType font) extension, 846 
TwelveHourClock class, 460-463 
Twist property, 1019 
typefaces, 845 

attributes of, 845 
Typelnfo objects, 114 
Typography class, 856-858 

u 

UlCommand class 

buttons, defining, 222 
context menu commands, 263 
UlCommandlnvokedHandler type, 227 
UlCommandSeparator objects, 263 
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velocity 


UlElement, 14 

CapturePointer method, 628 
ManipulationMode property, 656 
pointer-input events, 615 
Projection property, 377 
RenderTransformOrigin property, 377, 384 
RenderTransform property, 377 
TransformToVisual method, 427 
user-input events, 69, 140 
UIElementCollection class, 24, 38 
Ul thread (user-interface thread), 224-225 
animation callback methods in, 329 
animations in, 331 
callback methods, running in, 227 
PrintDocument object, creating and accessing, 911 
queuing methods to run, 225 
WriteableBitmap modifications in, 721 
UnconventionalAppBar project, 269-271 
underlining, 278, 285 
Unhand led Exception event handler, 317 
Unicode, 277 

surrogates, 277, 281 
UnicodeString property, 851 
UniformGrid panel, 487 

columns, calculating number, 496 
in ListBox, 495-497 
Orientation property, 487, 493 
units 

device-independent, 545 
screen size in, 553 
Unloaded events, 86 
UpdateBitmap method, 717, 719-721 
UpdatelmageTransforms method, 997, 999 
Update method, 836 
UpdateValues method, 366 
UserControl class 

classes deriving from, 188 
Content property, 38, 125 
custom controls, deriving from, 175-177 
deriving from, 124-126,141 
Popup child instances, 268 
with RadioButton controls, 289 
user input 

consolidation of touch, mouse, and pen input, 615 
from margin area, 101 
pen input, 616 

pointer input, 615. See also pointer input; touch 
transferring to View Model, 194 
user-input events, 69, 80-83 
controls, processing of, 140 
routed input handling, 74-75 
Tapped event, 69-72 


virtual methods for, 75 
user interface 

controls and elements of, accessing, 224-225 
dependency properties, 15 
threads for, 221, 223-225 
user settings, saving, 934 
using directives, 5 
organizing, 23-24 
removing unused, 23-24 
UTF-8 encoding, 277,886 
UTF-16 encoding, 277, 886 

UTF-32 (32-bit Unicode Transformation Format), 277 

V 

Validate method, 211 
ValueChanged events, 143, 667 
handler, 671 

ValueChanged handler, 142, 151, 281 
Value property, 62 

of DiscreteObjectKeyFrame, 372 
of PointKeyFrame class, 369 
of TransformGroup, 674 
VariableSizedWrapGrid panel, 130-131 
children, arrangement of, 97 
Orientation property, 130-131 
var keyword, 25 
Vector2 structure, 638-646 
Rotate method, 641-642 
vector graphics, 48-57 
centering objects, 50 
curves, 53 

element height and width, 49 
filling screen with object, 51 
HorizontalAlignment and VerticalAlignment, 49, 51 
image brushes, 52-53 
negative coordinates, 400 
Path element, 53-57 
PathGeometry element, 53-57 
scaling, 545 
stretching, 58-60 
vectors 

acceleration vectors, 966, 968 
accelerometer readings, 959-960 
defined, 959-960 
magnitude, 960, 961, 965 
two-dimensional, 970 
Velocities property, 663 
velocity 

calculating, 972 
two-dimensional, 970 
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VerticalAlignment property 


VerticalAlignment property, 8-9, 11, 97-101 
of Border element, 99 
of Canvas, 137 
Center setting, 108 
cropping shapes, 103 
default Stretch value, 98 
default value, 81 
of Ellipse, 102 

VerticalContentAlignment property, 140, 511 
VerticalScrollBarVisibility property, 113 
video display 

resolution, 15-16 
updating, 91 
videos, playing, 22 
View, 193-194 
Viewbox, 58-60 
Grid in, 401-402 
StretchDirection property, 59 
Stretch property, 58 
stroke width, 60 
TextBlock in, 494 
View Model, 193-194 

AddCharacterCommand property, 215-216 
application settings, saving, 308-311 
Button calls into, 212-213 
commands in, 213 
commands, processing, 213-219 
data bindings in, 194-196 
DataContext property, 205 
data entry validation, 210-211 
DeleteCharacterCommand property, 215-216 
DisplayText property, 215 
Execute and CanExecute methods, defining, 213 
ExecuteCalculate and CanExecuteCalculate 
methods, 215 
Inputstring property, 215 
instantiating in code, 205 
instantiating in Resources collection, 206 
as resource, defining, 198, 218 
updates, blocking, 211 
view model classes, 474 
view models 
creating, 594 

with data bindings, 794-797 
defining, 600-601 
instantiating, 612 
items, accessing, 594 
ObservableCollection type, 608-611 
ViewParams class, 1003 
virtualization of panels, 481-484 
VirtualizingStackPanel, 260, 482, 501,1050 
VirtualKey enumeration, 574 


Virtual Key values, 887 
virtual methods 

overriding, 76, 461 
for user-input events, 75 
virtual protected methods, 615 
Visibility property, 72, 461 
animating, 371-372 
bindings on, 462-463 
Collapsed setting, 516, 654 
Visible setting, 615 
VisitedPageSave program, 565-568 
Visual Basic, .NET API access, 779 
visual feedback, transforms for, 386-387 
visuals, control, defining, 125-126 
VisualStateGroups section, 514-515 
Visual State Manager, 513-520 
markup for, 602-603 
Snapped state, responding to, 583 
views, responding to, 583-584 
VisualStateManager class 
empty tags, 515 

GoToState method, 513, 516, 606 
VisualStateGroups section, 514-515 
visual states, 513-520 
brushes for, 521 
empty tags, 515-516 
SelectionStates group, 536 
triggering, 652 
Visual Studio 

application packages, creating, 824 
Blank App, 581 
Configuration Manager, 823 
design view, 8 

generic.xaml file generation, 530 

Get Started tab, 3 

Grid App projects, 539 

IntelliSense feature, 8. See also IntelliSense 

intermediate files, 25 

multiple instances, 130 

navigation classes, 581-588 

New Project dialog box, 3 

proxy classes for Web services, 1002 

sample view model, 581 

Simulator, 9 

Solution Configurations box, 821-822 

Solution Platforms box, 822 

Split App projects, 539 

Suspend, Resume, or Suspend And Shutdown 

commands, 246, 248 

text, pasting into, 17 

virtual methods, overriding, 76 
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Windows Store, uploading packages to 


Visual Studio debugger, 8 

application suspension and resumption, 246 
data, saving and restoring, 248 
exceptions, reporting on, 318 
Visual Studio Toolbox, 8 
visual tree, 14 
AppBar in, 270 
Button in, 503 


windows 

application, 5 
size changes, 539 
size, obtaining, 541 
Ul thread, 224-225 
Windows 8 

accessing, programming language and, 779 
documentation, 5 


climbing, 47 

DataContext property, propagation down, 204 

defining, 139-140, 451-452 

elements, accessing, 143 

events routing up, 78 

generating for items, 467, 473 

implicit styles, propagation of, 64-65 

Loaded events, 86 

parent-child hierarchy, 97 

precedence of settings, 63 

for printing, 904 

properties propagating through, 15 
visual state elements, 513 
VisualTreeHelper class, 47 


w 

WaitAII method, 1004 
Web browsers 

Back and Forward buttons, 562 
Internet Explorer, 269 
Web services, proxy classes for, 1002 
WebViewBrush class, 31 
WhatRes program, 540-545 
WhatSize program, 84-86 
WHATSIZE program, 83-84 
WhatSizeWithBindingConverter project, 110-112 
WhatSizeWithBindings project, 108-110 
WhatSnap program, 549-554 
WheresMyElement project, 427-430 
Whirligig program, 647-649 
Width property, 86 
Win32 API 

accessing, 779. See also P/Invoke (Platform Invoke) 
data type equivalence to C#, 780-781 
EnumDynamicTimeZonelnformation function, 787 
functions, documentation of, 780 
Hungarian notation, 780 
WinBase.h header file, 780 
Window class, 557 

Current property, 594 
Dispatcher property, 594 
windowing coordinate system, 33, 49 


retained mode graphics system, 83 
screen resolution adjustments, 540 
Windows Runtime Components, 779 
Windows 8 simulator, testing display sizes in, 543-544 
Windows 8 Sound Recorder, 22 
Windows 8 start screen 
moving items, 582 
selecting items, 582 
width and height, 97 
zooming items, 582 

Windows. Application Model. DataTransfer 
namespace, 898 

Windows. Application Model. DataTransfer. ShareTarget 
namespace, 898 

Windows.Devices.Geolocation namespace, 953 
Windows.Devices.Sensors namespace, 953 
/Windows/Fonts directory, 846 
Windows.Graphics.Display namespace, 554 
Windows.Graphics.Imaging namespace, 703 
Windows.Graphics.Printing namespace, 904 
Windows.Graphics. Printing.Option Details 
namespace, 904 
Windows header files, 780 
Windows * namespaces, 5 
Windows operating system 
font files, 846 

returning programmatic control to, 230 
Windows Paint, 12 
Windows Runtime 
class hierarchy, 13 

public classes, structures, and enumerations, 6-7 
Windows Runtime Components, 129, 779 
limitations on, 808 
Windows.Storage namespaces, 233 

Windows.Storage. Bulk Access namespace, 235 
Windows.Storage.Pickers namespace, 234 
Windows.Storage.Streams namespace, 694 
Windows Store applications, 779 
display resolution for, 549 
fonts, 847 

minimum screen size, 551 

Windows Runtime Component template, 808-809 
writing, 786-808 

Windows Store, uploading packages to, 824 
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Windows.Ul.Input.Inking namespace 


Windows.Ul.Input.Inking namespace, 1013, 1014 
Windows.Ul.Xaml.Controls namespace, 140 
Windows.Ul.Xaml.Controls.Primitives namespace, 140 
Windows.Ul.Xa ml. Media. Animation namespace, 329 — 
330 

using directive, 333 

windows.ui.xaml.media.dxinterop.h header file, 809 
Windows.UI.Xaml.Media.Media3D namespace, 430 
Windows.Ul.Xaml namespaces, 5 
Windows.Ul.Xa ml. Printing namespace, 904 
Windows.Ul.Xa ml. Shapes namespace, 57 
winnt.h header file, 780 
WordFreq project, 254-260 

cancellation and progress reporting, 257-258 
error reporting, 256-257 
Start and Cancel buttons, 256-257 
WORD values, 780 

WPF (Windows Presentation Foundation), 6 
wProcessorArchitecture field, 784-785 
formatting, 785 

WrapOptionsDialog objects, 290 
WrappedText project, 18-19 
wrapper DLLs, 779. See also DirectXWrapper library 
Windows Runtime Components, 779 
WriteableBitmap class, 646, 683 
array size, 686 
Color constructor, 762 
color format, 684 
constructor, 686 
instantiating, 685 
invalidating, 687 

line- and arc-drawing algorithms, 722-747 
PixelBuffer property, 683, 686 
pixel formats, 709 
premultiplied alphas, 684, 691, 762 
SetSource method, 683, 692 
sRGB color values, 684 
updating pixels, 717 
WriteAsync method, 686 
WriteBufferAsync method, 244 
WriteFactory class 

GetSystemFontCollection method, 812 
header file, 810 
WriteFont class, 818-819 
header file, 818 

WriteFontCollection class, 811-813 
WriteFontCollection.h header file, 811, 812 
WriteFontFamily class header file, 813-814 
WriteTextAsync method, 248, 249, 319 
wrl.h (Windows Runtime Library) header file, 809 


X 

XAML 

Angle property, setting, 380 
animations in, 359-363 
conditional execution, 460-463 
experimenting with, 293. See also XamICruncher 
local namespace declaration, 327 

XamICruncher, 293-308 
Add button, 320 
animations in, 361 
application bar, 294 
AppSettings class, 308-311 
bindings in, 313 
Button definitions, 313 
ChecklfOkToTrashFile method, 320 
code-behind file, 313-315 
constructor, 313-315 

dependency property definitions, 301-302 
editor, 293 

EditOrientation enumeration, 308 

EditOrientationRadioButton controls, 322-327 

exception handling, 316-318 

file I/O, 318-321 

file-saving logic, 307-308 

Grid, 313 

limitations, 327 

Loaded handler, 313-315 

MainPage.xaml, 311-315 

Open button, 320 

Orientation property, 297 

page configuration, 293 

property-changed handlers, 297-300, 303-305 

Refresh button, 294 

ruler and grid lines, 294,301 

Save and Save As buttons, 318-319 

saving documents, 318-319 

SetDefaultXamIFile method definition, 315 

Settings dialog, 322-327 

SplitContainer, 295, 313 

status bar, 313 

TabbableTextBox class, 306-307 
Thumb control, 295 

XAML (extensible Application Markup Language), 6 
attribute names, 133 
content properties, 37-41 
data bindings, 66-68 
elements and controls, coding, 23-27 
for layout and appearance of page, 69 
markup extensions, 44, 67 
MVVM pattern, 193 
object elements, 35 
Path Markup Syntax, 55-57 
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XAML (extensible Application Markup Language) 
{continued) 

property attributes, 35 
property elements, 35 
property-element syntax, 34-37 
resource sharing, 43-47 
stretching graphics, 58-60 
styles, 60-65 
syntax, 19, 31-68 
TextBlock content property, 41-43 
vector graphics, 48-57 
XAML files 

compatibility, 6 
control updating logic, 144 
control visuals, defining, 125 
elements, instantiating, 38 
images, referencing, 12 
names in, 23 
parsing, 25 

resource definitions, 46 
resources section, 44 
root tags, placing content between, 177 
templates in, 467-469 
View and View Model interactions, 194 
visual elements, defining, 6 
visual tree of elements, 14 
XAML parser, 24 
XamIReader class, 293, 316-317 
XamIReader.Load method, 56 
XAML resources, 43-47 
x:Boolean type, 44 
x:Class attribute, 6, 7 
x:Double type, 44 
x:lnt32type, 44 
x:Key attribute, 44, 61, 62 
XML (extensible Markup Language) character 
escaping, 17 

XmlSerializer class, 592-594 
x:Name attributes, 23, 69 

on VisualStateGroup and VisualState tags, 515 
x:Null markup extension, 68 
"x 〃 prefix, 7, 23, 44, 68 
XPS packages, 852-853 
XPS (XML Paper Specification), 852-853, 856 
x:String type, 44 
x:Uid type, 68 


XYSlider controls, 667-672 
with Pointer events, 749-752 
Point property, 667 
SetCrossHair method, 669 
template, defining, 670-671 
ValueChanged event handler, 671 
XYSliderDemo project, 670-672 



YawDegrees property, 980 
YawPitchRoll program, 976-980 
YellowPadPage class, 1043 
blue rule lines, 1043-1044 
InkFileManager property, 1044 
YellowPad project, 1038-1056 
application bar items, 1038 
Bezier rendering logic, 1039-1041 
blue rule lines, 1043-1044 
buttons, handling, 1050-1052 
controls, initializing, 1052-1053 
copy, cut, paste, and delete functions, 1053 
current page index, 1049-1050 
FlipView control, 1038,1043 
LoadAsync and SaveAsync methods, 1038 
number of pages, 1049-1050 
page numbers, 1048-1049 
Paste logic, 1050-1052 
pen width and color selection, 1050-1052 
Yield property, 259-260 
YoungGoodmanBrown project, 863-866 

z 

Z axis, 413 

rotation around, 431 
z equals 1, 414 
z-index, incrementing, 190 
Zlndex property, 136-137, 190, 435 
ZoomMode property Disabled setting, 112 
zoom, semantic, 582 
Z order, 20 
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